> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-lifecycle/resolution.md).

# Resolution

Discover how Pharos helps with resolving problems through AI analysis and tracing.

Resolution is the final and most important stage of the Issue lifecycle—actually fixing the underlying problem. Pharos provides multiple tools to accelerate debugging and ensure fixes are complete and verified.

## The Resolution Mindset

Before diving into debugging tools, understand the resolution philosophy:

**Resolution ≠ Debugging**\
Resolution is about *eliminating* the Issue permanently, not just understanding it. The goal is:

* Implement a fix that addresses the root cause
* Deploy the fix to production
* Verify the Issue stops occurring
* Document what was fixed for future reference

**Typical Resolution Timeline:**

* **Hours:** Simple fixes (null checks, validation rules, configuration)
* **Days:** Moderate complexity (logic errors, integration issues)
* **Weeks:** Complex fixes (architecture changes, governor limit optimization)

## Resolution Workflow

Resolution follows an eight-step workflow, from investigating the error through closing the Issue once the fix is confirmed.

### Step 1: Investigate

Use the debugging tools available on the Issue record to understand what's breaking and why.

#### Debug Views and Stack Traces

Every Issue provides access to debug information from the underlying logs.

**Accessing Debug Information:**

Navigate to the **Debug** tab on the Issue record. This shows:

* **Apex stack traces:** Full call stack showing class → method → line number
* **Flow execution paths:** Element sequence, decision outcomes, loop iterations
* **Process Builder traces:** Process definition, criteria nodes, actions triggered
* **Integration error details:** Endpoint, HTTP status, response context

**What You'll See:**

For **Apex errors:**

```
Exception: System.NullPointerException
Class: OpportunityTriggerHandler
Method: afterInsert
Line: 156

Stack Trace:
  OpportunityTriggerHandler.afterInsert (line 156)
  TriggerHandler.run (line 45)
  OpportunityTrigger (line 12)
```

For **Flow errors:**

```
Flow: Account_Creation_Flow (version 12)
Failed Element: Validate_Industry
Element Type: Decision
Error: Required field missing: Industry
```

**Key Insight:** The debug view references the *first log* that created the Issue by default. However, all logs under this Issue have similar debug information—you can click through individual logs if needed for specific record context.

#### Impact Analysis

Before fixing, understand the scope:

**User Impact:**

* How many users are affected?
* Are they internal (admins, developers) or external (customers, partners)?
* What profiles/roles are hitting this error?
* Is there a workaround users can use temporarily?

**Data Impact:**

* Which records are failing to process?
* Is data being corrupted or just not saved?
* Can we export affected record IDs for manual remediation?
* What downstream processes depend on this data?

**Download Impacted Records:**

On the Issue's **Data Impact** tab:

1. Navigate to **All Time** subtab
2. Click **Download CSV**
3. Open file → Contains all impacted record IDs, object types, and timestamps
4. Use Data Loader or manual updates to remediate if needed

#### Occurrence Patterns

Check the **Occurrence** chart to understand when and how often the error happens:

* **Daily pattern:** Persistent problem, likely affects normal user workflow
* **Single spike:** One-time data load issue, likely resolved already
* **Increasing frequency:** Problem getting worse, prioritize fix
* **Sporadic:** Hard to reproduce, may need tracing (see below)

### Step 2: Analyze Root Cause

Now that you understand *what* is failing, determine *why*.

#### Common Root Causes by Category

**Apex Exceptions:**

* `NullPointerException` → Missing null check before dereferencing variable
* `DmlException` → Validation rule, required field, duplicate detection, trigger recursion
* `LimitException` → SOQL query limit, CPU timeout, heap size exceeded
* `QueryException` → No rows returned when expecting one, too many rows for LIMIT 1

**Flow Failures:**

* Required field missing → Validation rule not accounted for in flow logic
* Record locked → Flow trying to update record being edited by user
* CPU timeout → Loop running too many iterations, inefficient queries
* Null variable → Decision referencing empty variable, get record returned no results

**Process Builder Errors:**

* Flow called from process failed → Check flow error (see above)
* Recursion → Process triggering itself via related object updates
* Governor limits → Too many processes firing on same transaction

**Bulk API Failures:**

* Duplicate value → Upsert using wrong external ID field
* Required field missing → Source data incomplete
* Validation rule → Data doesn't meet org's validation criteria
* Inactive owner → Trying to assign record to inactive user

#### Using AI Analysis

Pharos AI can help suggest potential causes:

1. Navigate to **AI Analysis** tab on Issue
2. Review suggested root causes based on error pattern
3. Check similar issues across your org
4. Reference documentation links for Salesforce-specific errors

{% hint style="info" %}
AI Analysis availability and capabilities vary by Pharos version. Check your admin console for enabled features.
{% endhint %}

### Step 3: Trace (If Needed)

For intermittent or hard-to-reproduce issues, **Tracing** captures full debug logs around error occurrences.

#### When to Use Tracing

Reach for tracing when an error is hard to catch through normal testing:

* Error happens sporadically (can't reproduce on-demand)
* Need to see variable values at time of failure
* Intermittent governor limit issues (need to see what else ran in transaction)
* User-reported issue but you don't see it in your testing

#### How Tracing Works

**Initiating a Trace:**

1. From Issue record, navigate to **Tracing** related list
2. Click **New Trace Schedule**
3. Define **Trace Windows** (time periods when trace is active)
   * Example: Monday 9 AM - 5 PM (when users report issue happens most)
4. Set **Captured Trace Log Window** (how many logs before/after to capture)
   * Default: 5 (captures a couple of logs before and after the error log)
5. Activate trace schedule

**What Gets Captured:**

When the Issue's fingerprint is detected during an active trace window:

* Full Salesforce debug log for the transaction
* Surrounding logs (before/after) for context
* Highlighted indicator showing which log contains the error
* All variable values, SOQL results, DML operations, CPU time

**Viewing Trace Results:**

1. Refresh Issue page after trace window completes
2. Navigate to **Trace Results** related list
3. Click on result → See all captured logs
4. Download raw logs if preferred for external analysis (Chrome extension, VS Code)

**Trace Schedule Management:**

* Only one **active** trace schedule per Issue
* Multiple trace windows allowed within one schedule
* Schedule auto-deactivates after last window completes
* Create new schedule if you need to trace again later

{% hint style="warning" %}
**Trace Impact:** Tracing captures full debug logs, which consume API call limits and storage. Use judiciously for Issues that truly need deep debugging.
{% endhint %}

### Step 4: Develop Fix

Now implement the solution.

#### Typical Fixes by Error Type

**Null Pointer Exceptions:**

```apex
// Before (breaks):
Account acc = [SELECT Id FROM Account WHERE Name = 'Test'];
acc.Industry = 'Technology'; // Breaks if no account found

// After (fixed):
List<Account> accounts = [SELECT Id FROM Account WHERE Name = 'Test'];
if (!accounts.isEmpty()) {
    accounts[0].Industry = 'Technology';
}
```

**Flow Required Field Errors:**

* Add decision before record creation to validate all required fields populated
* Update screen flow to mark fields as required
* Add fault path to handle gracefully and show user-friendly error message

**Governor Limit Timeouts:**

* Bulkify code (move SOQL/DML outside loops)
* Reduce query result size (add filters, use selective queries)
* Split batch job into smaller chunks
* Use queueable/future methods to split CPU time across transactions

**Validation Rule Conflicts:**

* Update validation rule criteria to account for automation
* Modify flow/process to set fields in correct order
* Use System Mode (Flows) or `allOrNone=false` (DML) if appropriate

#### Development Best Practices

* **Fix in sandbox first** → Never edit directly in production
* **Write unit tests** → Ensure fix works and doesn't break other functionality
* **Test with real data** → Use production-like data volumes and scenarios
* **Document the fix** → Add code comments explaining why change was needed

### Step 5: Test

Verify your fix works before deploying to production.

#### Testing Checklist

* [ ] Reproduce the original error in sandbox
* [ ] Apply fix
* [ ] Confirm error no longer occurs
* [ ] Test related functionality (didn't break something else)
* [ ] Check governor limits (didn't introduce new performance issue)
* [ ] Run unit tests (all pass, code coverage sufficient)

#### Testing for Different Scenarios

**Apex fixes:**

* Run unit tests for the class
* Manually execute the trigger/process that was failing
* Test with multiple records (bulk testing)

**Flow fixes:**

* Run flow in debug mode
* Test all decision paths (not just the one that failed)
* Test as different user profiles (permission issues)

**Configuration fixes:**

* Try the original failing scenario
* Test edge cases (what if field is blank? what if user doesn't have permission?)

### Step 6: Deploy

Release your fix to production.

**Deployment Steps:**

1. Create changeset/package from sandbox
2. Deploy to production (use deployment window if policy requires)
3. Run post-deployment tests
4. Monitor immediately for new errors

**Update the Issue:**

1. Navigate to Issue record in Salesforce
2. Update status to `In Review` (monitoring for recurrence) or `Completed` (confident fix works)
3. Add comment:

   ```
   Fix deployed: [Date]
   Changeset: [Link or ID]
   Summary: Added null check in OpportunityTriggerHandler line 156
   ```

### Step 7: Monitor

Watch to ensure the Issue stops occurring.

**Monitoring Period:**\
Recommended: 1-2 weeks after deployment

**What to Check:**

* **Occurrence chart** → No new logs appearing
* **Last Occurred date** → Should remain static
* **Log count** → Should stop incrementing

**If Issue Reoccurs:**

* Pharos will automatically reopen it (status → `New`, regression → `true`)
* You'll receive notification (if configured)
* Indicates fix was incomplete or only addressed part of the problem
* Investigate again—may need different approach

### Step 8: Close

Mark the Issue as fully resolved.

**When to Mark Completed:**

* No recurrence after monitoring period
* Confident root cause addressed
* No related Issues still open

**Final Documentation:** Update Issue with final comment:

```
Issue confirmed resolved.
No recurrence since deployment on [Date].
Total fix time: [X days from Action to Completed]
Root cause: [Brief summary]
```

## Handling Special Resolution Scenarios

Some Issues don't follow the standard workflow. The scenarios below cover the most common exceptions and how to approach each.

### Scenario 1: Can't Reproduce

**Problem:** Error shown in logs but you can't make it happen in sandbox.

**Approach:**

1. Use Tracing to capture full debug logs when it happens in production
2. Check if it's user-specific (permissions, record access)
3. Compare production data vs. sandbox data (missing records?)
4. Check if it's time-based (scheduled job, specific time of day)

### Scenario 2: Intermittent Governor Limits

**Problem:** CPU timeout or SOQL limit happens sometimes but not always.

**Approach:**

1. Check **Occurrence** chart—does it correlate with high-usage times?
2. Use Tracing to see what else ran in same transaction
3. Look for triggers stacking (multiple triggers on same object)
4. Check for recursion (trigger → workflow → process → trigger loop)

### Scenario 3: External System Timeout

**Problem:** Logs with integration payloads show HTTP timeout or connection refused.

**Approach:**

1. Check if external system was down at time of error (check their status page)
2. Review timeout settings (can they be increased?)
3. Implement retry logic with exponential backoff
4. Add fault paths to handle gracefully and alert operations team

### Scenario 4: Cannot Fix (Salesforce Bug)

**Problem:** Issue is caused by Salesforce platform bug, not your code.

**Approach:**

1. Search Salesforce Known Issues for your error
2. Open case with Salesforce Support, provide Issue link
3. Mark Issue as `Blocked` or add custom status `Pending Vendor`
4. Add comment with case number
5. Revisit when Salesforce resolves their bug

## Regression Detection: Automatic Reopening

If an Issue marked `Completed` starts occurring again, Pharos automatically:

* Sets status back to `New`
* Marks **Regression** checkbox as `true`
* Captures **Regressed On** date
* Clears **Resolved On**
* Creates new ticket in ADO/Jira (if integration enabled)
* Sends notification (if configured)

**Resolved On** is stamped by ticket-resolution sync when the linked ticket resolves—regression clears it until the Issue is resolved again.

**Why This Matters:**

* Catches incomplete fixes (only solved one scenario, not all)
* Detects when new code reintroduces old bug
* Ensures no resolved problem is forgotten

**When Regression Occurs:**

1. Investigate why fix didn't work completely
2. Check if new deployment broke previous fix
3. Expand fix to handle additional scenarios
4. Redeploy and monitor again

## Measuring Resolution Effectiveness

Track these to improve your resolution process:

| Metric                             | Target                     | Insight                                     |
| ---------------------------------- | -------------------------- | ------------------------------------------- |
| **Mean Time to Resolution (MTTR)** | <14 days for High priority | Are fixes deployed quickly?                 |
| **Regression Rate**                | <5%                        | Are fixes thorough?                         |
| **First-Time Fix Rate**            | >90%                       | Do we understand problems before deploying? |
| **Issues Resolved Per Sprint**     | Increasing trend           | Is backlog shrinking?                       |

***

{% hint style="success" %}
**Resolution Tools Deep Dive:**

* [Tracing](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing.md) – Full guide to trace schedules and debug log capture
* [AI Analysis](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis.md) – Leveraging AI-suggested root causes
* [Debug Views](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/debug-views.md) – Interpreting stack traces and error messages
* [Impact Statistics](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/impact-statistics.md) – Understanding user and data impact
  {% endhint %}
