> 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-details/debug-views.md).

# Debug Views

Access debug views from the issue record with references to log debug views.

Debug views provide the technical details needed to understand **why** an error is occurring. While impact and occurrence metrics help with prioritization, debug information is essential for actual resolution.

## What Are Debug Views?

Debug views present the error's technical context in a human-readable format, including:

* Stack traces (for Apex errors)
* Flow execution paths (for Flow errors)
* Process Builder execution details
* Bulk API error messages
* Error messages and exception types

These views aggregate debug information from the **first log** that created the Issue by default, though you can drill into individual logs for specific occurrences.

## Accessing Debug Information

### On the Issue Record

Navigate to the **Debug** tab on the Issue details page. This displays the technical error information inherited from the first log.

**What you'll see:**

* Error category (Apex, Flow, Process Builder, Bulk API)
* Error type (DmlException, NullPointerException, etc.)
* Stack trace or execution path
* Error message text

### On Individual Log Records

For record-specific context:

1. Navigate to **Related Logs** related list
2. Click on a specific log
3. View that log's **Debug** tab

**Why drill into individual logs?**

* See error with specific record IDs
* Compare different occurrences for patterns
* Investigate if error manifests differently for certain data

## Debug Views by Error Category

The debug view adapts to the error category, presenting the details that matter most for Apex, Flow, Process Builder, and integration errors.

### Apex Errors

For Apex exceptions, the debug view shows a **stack trace**—the sequence of method calls leading to the failure.

**Typical stack trace format:**

```
Exception Type: System.NullPointerException
Message: Attempt to de-reference a null object

Stack Trace:
  Class.OpportunityTriggerHandler.afterInsert: line 156, column 12
  Class.TriggerHandler.run: line 45, column 8
  Trigger.OpportunityTrigger: line 12, column 1
```

**Reading the stack trace:**

| Element                        | Meaning                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------- |
| **Exception Type**             | Category of error (NullPointerException, DmlException, LimitException, etc.) |
| **Message**                    | Salesforce's description of what went wrong                                  |
| **Class.ClassName.methodName** | Which class and method was executing                                         |
| **line X, column Y**           | Exact location in code where error occurred                                  |
| **Stack order**                | Top = where error happened, bottom = entry point                             |

**Example interpretation:**

```mermaid
graph TD
    A[OpportunityTriggerHandler.afterInsert line 156 - error occurred]
    B[TriggerHandler.run line 45]
    C[OpportunityTrigger line 12 - entry point]
    C -->|called| B
    B -->|called| A
```

*Translation: Opportunity record was inserted, trigger fired, called TriggerHandler.run, which called afterInsert method, which failed at line 156 with a null pointer.*

**Common Apex error types:**

* **System.NullPointerException** → Tried to access property/method on null object
* **System.DmlException** → Database operation failed (validation, required field, duplicate, etc.)
* **System.LimitException** → Governor limit exceeded (SOQL, DML, CPU time, heap)
* **System.QueryException** → Query returned unexpected results (too many, zero when expected one)
* **System.TypeException** → Data type mismatch or invalid cast

### Flow Errors

For Flow failures, the debug view shows the **flow execution path**—which elements ran and where it failed.

**Typical flow debug format:**

```
Flow: Account_Creation_Flow (version 12)
Interview GUID: 301xx0000000ABCD

Failed Element: Validate_Industry
Element Type: Decision
Error: The flow tried to update these records: null. 
       This error occurred: REQUIRED_FIELD_MISSING: Required fields 
       are missing: [Industry]

Execution Path:
  [Start] → Get_Account_Record → Validate_Industry (FAULT)
```

**Reading the flow debug:**

| Element                 | Meaning                                                  |
| ----------------------- | -------------------------------------------------------- |
| **Flow name + version** | Which flow and which version failed                      |
| **Failed Element**      | API name of the element where error occurred             |
| **Element Type**        | Decision, Assignment, Record Update, Subflow, Loop, etc. |
| **Error message**       | Salesforce's description of the problem                  |
| **Execution Path**      | Sequence of elements that ran, ending at FAULT           |

**Common Flow error patterns:**

* **REQUIRED\_FIELD\_MISSING** → Validation rule or required field not populated
* **INVALID\_TYPE\_ON\_FIELD\_IN\_RECORD** → Data type mismatch (text in number field, etc.)
* **CPU\_TIME\_LIMIT\_EXCEEDED** → Flow took too long (loops, too many queries)
* **RECORD\_LOCKED** → Trying to update record being edited by user
* **Null variable reference** → Decision or assignment using empty variable

**Visual representation:**

Some Pharos installations include a **visual flow diagram** showing:

* Executed elements (highlighted green)
* Failed element (highlighted red)
* Skipped branches (grayed out)
* Fault path (if configured)

This makes it easy to see which decision branch was taken and where execution stopped.

### Process Builder Errors

Process Builder failures show similar information to flows, since Process Builder often calls flows or Apex.

**Typical process builder debug:**

```
Process: Account_Update_Process (version 5)
Action: Launch_Account_Validation_Flow

Error: Flow Interview failed
  Flow: Account_Validation_Flow
  Error: REQUIRED_FIELD_MISSING: [Industry]

Criteria Node: Industry_Is_Empty (evaluated TRUE)
Action Type: Flow
```

**Reading process builder debug:**

| Element                    | Meaning                                           |
| -------------------------- | ------------------------------------------------- |
| **Process name + version** | Which process definition failed                   |
| **Criteria Node**          | Which criteria was met (TRUE evaluation)          |
| **Action**                 | Which immediate or scheduled action was executing |
| **Action Type**            | Flow, Apex, Field Update, Email Alert, etc.       |
| **Nested error**           | If action calls flow/apex, shows that error       |

**Common patterns:**

* Process calls Flow → Flow fails (see flow error details)
* Process calls Apex → Apex fails (see stack trace)
* Process creates record → Validation rule blocks it
* Recursion → Process triggers itself through related object updates

### Bulk API Errors

For Bulk API failures, the debug view shows operation context and per-record errors.

**Typical bulk API debug:**

```
Operation: Insert
Object: Account
Job ID: 750xx0000000ABC
Batch ID: 751xx0000000XYZ

Error Summary:
  Total Records: 1,000
  Failed: 15
  Succeeded: 985

Sample Failures:
  Record 1: REQUIRED_FIELD_MISSING - Required fields missing: [Name]
  Record 2: DUPLICATE_VALUE - Duplicate external ID: ACC-12345
  Record 3: REQUIRED_FIELD_MISSING - Required fields missing: [Name]
```

**Reading bulk API debug:**

| Element             | Meaning                                  |
| ------------------- | ---------------------------------------- |
| **Operation**       | Insert, Update, Upsert, Delete           |
| **Object**          | Which Salesforce object                  |
| **Job/Batch IDs**   | Bulk API identifiers for troubleshooting |
| **Error Summary**   | Total, failed, succeeded counts          |
| **Sample Failures** | First few failed records with reasons    |

**Common Bulk API errors:**

* **REQUIRED\_FIELD\_MISSING** → Source data missing required fields
* **DUPLICATE\_VALUE** → Unique field constraint violated
* **UNABLE\_TO\_LOCK\_ROW** → Record locked by another transaction
* **INACTIVE\_OWNER\_OR\_USER** → Trying to assign to inactive user

### Integration Errors

For logs carrying integration payloads—external system callouts and REST interactions—debug views show HTTP context and response details.

**Typical integration debug:**

```
Endpoint: https://api.external-system.com/v1/orders
Method: POST
Status Code: 500

Request Headers:
  Authorization: Bearer ***
  Content-Type: application/json

Response Body:
  {"error": "Internal Server Error", "message": "Database connection timeout"}

Error: HTTP 500 - Integration failed
```

**Common integration errors:**

* **Timeout** → External system didn't respond in time
* **401 Unauthorized** → Authentication failed
* **404 Not Found** → Endpoint doesn't exist or moved
* **500 Internal Server Error** → External system problem

## Using Debug Views for Root Cause Analysis

### Step 1: Identify Error Type

Start by understanding the category:

* **NullPointerException** → Missing null check
* **DmlException** → Validation or data issue
* **LimitException** → Performance/governor limit
* **Flow REQUIRED\_FIELD\_MISSING** → Validation rule or required field

### Step 2: Locate Failure Point

Find exactly where it's breaking:

* **Apex:** Class name, method name, line number
* **Flow:** Failed element name and type
* **Process Builder:** Action that failed

### Step 3: Understand Context

Use the error message and stack trace to understand:

* What operation was being attempted?
* What data was involved?
* What condition caused the failure?

### Step 4: Reproduce (if needed)

With debug information:

1. Navigate to the referenced code (Apex class, Flow definition)
2. Identify the failing line/element
3. Set up test scenario with similar data
4. Reproduce in sandbox for safe debugging

## Debug Views and Related Logs

The Issue's debug view shows the **first occurrence**, but sometimes you need to see multiple occurrences.

**When to review multiple logs:**

* Error message varies slightly (different record IDs, different field names)
* Suspect data-specific pattern (certain record types always fail)
* Intermittent issue (sometimes passes, sometimes fails)
* Need to see full debug log (beyond stack trace)

**Workflow:**

1. From Issue, go to **Related Logs**
2. Sort by **Created Date** (most recent first)
3. Open 3-5 recent logs
4. Compare their debug views for patterns

## Downloading Debug Logs

For deep analysis, you can download full Salesforce debug logs:

### When Full Logs Are Available

Full logs are only available under a few conditions:

* Tracing has been initiated (see [Tracing](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/tracing.md))
* Org has Pharos debug log capture enabled
* Log retention policy includes this timeframe

### Download Process

When a full log is available, download it in a few steps:

1. Navigate to log record (from Related Logs list)
2. If **Download Debug Log** button appears, click it
3. Opens `.log` file (text format)
4. Analyze in VS Code, Chrome extension, or Salesforce IDE

**What full logs contain:**

* Complete execution timeline (timestamps for each operation)
* All SOQL queries with results
* All DML operations
* Variable assignments
* Method entry/exit
* CPU time and heap usage at each step

## Limitations of Debug Views

### Line Numbers Can Change

Stack traces show line numbers, but:

* Code deployments may shift lines
* Refactoring changes line numbers
* View as approximation, not absolute reference

**Fingerprinting handles this** by ignoring line numbers when grouping errors.

### First Log May Not Be Representative

The Issue shows the first log's debug info, but:

* First occurrence might be edge case
* Later occurrences might have different data context
* Always check a few recent logs for current state

### Flow Versions

Flow errors are version-specific:

* Debug view shows version number
* If flow has been updated, debug may reference old version
* Check if new version exists and error still occurs

## Tips for Effective Debugging

### Compare Before Deployment

When debugging:

1. Note the error's First Occurred date
2. Check deployment history around that date
3. Review what changed (code, config, flows)
4. Likely culprit is what deployed just before

### Use Stack Trace to Navigate Code

In VS Code or Developer Console:

1. Copy class name from stack trace
2. Open that file
3. Jump to line number
4. Review code logic and null checks

### Cross-Reference with Documentation

Error messages often link to Salesforce docs:

* Google the exact error message
* Check Salesforce Known Issues
* Review Trailhead modules for that error type

{% hint style="success" %}
**Next Steps:**

* [Tracing](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/tracing.md) – Capture full debug logs for deep analysis
* [Related Logs](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/related-logs.md) – Drill into specific occurrences
* [Resolution](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-lifecycle/resolution.md) – Full resolution workflow using debug views
  {% endhint %}
