SfSkills Domains Docs GitHub

Home / flow / flow-runtime-error-diagnosis

flow-runtime-error-diagnosis

Use when a Salesforce Flow throws a runtime error, sends an unhandled fault email, or produces unexpected results in production or sandbox. Triggers: 'Flow error email', 'Flow failed at element', 'null reference in Flow', 'Flow SOQL limit error', 'Flow DML in loop error'. NOT for changing who receives fault emails or suppressing noisy ones — use flow/flow-error-notification-patterns. NOT for designing fault paths before anything fails — use flow/fault-handling. NOT for org-wide error alerting and trends — use flow/flow-error-monitoring.

Open the skill folder on GitHub

Flow Runtime Error Diagnosis

Use this skill when a Salesforce Flow generates a runtime error — either producing an unhandled fault email, displaying an error to the user, or failing silently on certain records. This covers reading the fault notification email, interpreting error types, tracing the failure to the specific element, and adding fault path handlers or fixing the root cause.

This is the incident-response companion to flow/fault-handling (which covers design-time prevention) and flow/flow-testing (which covers regression safety). When a Flow has actually failed in production, this skill is the one you open.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Flow Fault Notification Email

When a Flow encounters an unhandled error, it sends a fault email (if configured in Setup → Process Automation Settings → Send Flow Error Emails). The email contains:

FieldContents
Flow label and API nameIdentifies which flow
Flow versionThe version that ran (important — multiple versions may be active via flow version management)
Element API name where the error occurredE.g., Get_Account_Records or Create_Case_0
Error messagePlatform-specific error, e.g., INVALID_FIELD: Account.NonExistentField__c
Stack trace of element execution orderShows which elements ran before the failure
Context variable valuesInput variables and selected $Record field values at the time of failure

Reading the element name from the email is the fastest way to navigate directly to the failing element in Flow Builder.

Common Runtime Error Types

Error TypeLikely CauseCommon Fix
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITYValidation rule, duplicate rule, or trigger failure on the DMLFix the underlying validation rule or add error handling
INVALID_FIELDField referenced in Flow no longer exists or was renamedUpdate the Get/Create element to remove or replace the deleted field
NULL_REFERENCEVariable used in formula or decision without null checkAdd a null check decision before the element that uses the variable
LIMIT_EXCEEDED (SOQL)Too many SOQL queries — usually DML/Get in a loopMove Get Records element outside the loop
LIMIT_EXCEEDED (DML)Too many DML statements — DML inside a loopUse Collection-based approach instead of per-record DML
FIELD_INTEGRITY_EXCEPTIONRequired field not set or picklist value invalidVerify field values before the DML element
NUMBER_OUTSIDE_VALID_RANGEAssignment to a Number/Currency field with a value exceeding precisionClamp the value or change the field's precision
INSUFFICIENT_ACCESS_OR_READONLYRunning user lacks FLS or object perm on a field the Flow touchesGrant FLS / adjust running-user context / use "run in system mode"
UNABLE_TO_LOCK_ROWRecord lock contention from concurrent updatesRetry pattern OR reduce per-interview DML
QUERY_TIMEOUTFlow's Get Records query too expensive or too broadAdd selective filter or index the filter field
STRING_TOO_LONGAssigning a value > field's max lengthTruncate or validate input length before assignment

Fault Paths

A Fault Path is a connector from a Flow element (Get Records, Create Records, etc.) that runs when that element fails, instead of the normal path. Without a fault path, the error is unhandled — it shows a generic error to the user and sends a fault email.

To add a fault path: In Flow Builder, click the element → Add Fault Path → connect to a fault-handling sub-flow or screen.

See flow/fault-handling for the FOUR canonical fault-routing patterns; this skill's job is to decide WHICH pattern fits the failure being diagnosed.

Debug Mode for Diagnosing the Root Cause

Flow Builder's Debug mode (Run → Debug) allows executing the flow with specific input values and tracing each element's execution:

  1. In Flow Builder, click Debug.
  2. Enter input variable values (e.g., a Record ID for a record-triggered flow).
  3. Click Run — the debug panel shows each element that executed, the variable values at each step, and where the flow stopped.

For Record-Triggered Flows in production, the equivalent is running with debug enabled from a specific record's Flows button (if exposed), or using the Flow Debug Trace in the setup area.

Debug mode limitations:

For bulk-specific failures, Debug won't reproduce — use sandbox bulk load + Flow Interview Log forensics.

Common Patterns

Pattern 1: Tracing NULL_REFERENCE to Its Source

When to use: Flow error: NullPointerException or NULL_REFERENCE error pointing to a formula or decision element.

Steps:

  1. Identify the element that failed from the error email.
  2. In Flow Builder, look at the failed element's inputs — which variable is used there?
  3. Trace that variable backwards to where it is set (Get Records element, assignment, or input variable).
  4. Common cause: Get Records returned no records (null), and the next element tries to access a field on the null record.
  5. Fix: Add a Decision element after Get Records to check {!recordVariable} is null. Route the null path to a graceful outcome (Pattern A from flow/fault-handling).

Pattern 2: Diagnosing SOQL Limit Errors

When to use: Flow error: LIMIT_EXCEEDED: Too many SOQL queries: 101

Steps:

  1. Look for a Get Records or subflow inside a Loop element in the failing flow.
  2. Get Records inside a loop queries for each iteration — 200 iterations = 200 SOQL queries.
  3. Fix: Move the Get Records element outside the Loop. Retrieve all needed records once before the loop. Use a Collection Filter within the loop to find the relevant record from the already-retrieved collection.
  4. Cross-reference flow/flow-bulkification Pattern 1 (Query-once + reuse).

Pattern 3: INVALID_FIELD After Schema Change

When to use: Flow error: INVALID_FIELD on a field that used to work.

Steps:

  1. Check recent deployments — was the field renamed or deleted?
  2. Run field-impact-analyzer (runtime agent) or probe_apex_references MCP tool to find all other automation that references the same field — other flows, Apex, VRs may be affected too.
  3. Fix: update the flow element to reference the renamed field OR restore the deleted field OR remove the reference from the flow.
  4. Add a monitoring reminder: when a field is deleted/renamed in future, audit flow dependencies FIRST.

Pattern 4: UNABLE_TO_LOCK_ROW Contention

When to use: Flow error: UNABLE_TO_LOCK_ROW on DML elements under high concurrency.

Steps:

  1. Check what else writes to the same record concurrently (triggers, other flows, external integrations).
  2. The lock is held by whoever opened the save transaction first — your Flow is losing the race.
  3. Fix options:
    • Reduce Flow's critical-section time (move work out of the transaction via async).
    • Serialize concurrent writers via Platform Events queue.
    • Retry pattern (Pattern B from flow/fault-handling).
    • If contention is from data loads, stagger or batch differently.

Pattern 5: The "Works in Debug but Fails in Production" Trap

When to use: Flow passes debug mode in Flow Builder but fails in production.

Cause: Debug mode runs in simulated context — no real Apex triggers, no real DML commits, system-admin-like access. Production has all of those.

Diagnostic steps:

  1. Confirm the flow's running user context in production vs debug (System Admin always passes; real users may not).
  2. Check whether object/field permissions differ.
  3. Check whether Apex triggers on the object are performing additional DML that the flow is contending with.
  4. Reproduce in sandbox under the actual running user's profile — that's the true test.

Decision Guidance

Error TypeFirst CheckLikely Fix
INVALID_FIELDHas a field been deleted or renamed recently?Update the element referencing the missing field (Pattern 3)
NULL_REFERENCEDoes the element use a record variable from Get Records?Add null check after Get Records (Pattern 1)
SOQL limitIs there a Get Records inside a Loop?Move Get Records outside the loop (Pattern 2)
DML limitIs there a Create/Update/Delete inside a Loop?Collect records in a collection, bulk DML outside loop
CANNOT_INSERT_UPDATEDoes the record fail a validation rule or duplicate rule?Fix the validation rule or check values before DML
Error on some records, not allIs there a conditional path missing a null check?Add Decision element to handle edge cases
UNABLE_TO_LOCK_ROWIs another process writing to the same record concurrently?Pattern 4 — serialize, retry, or async
INSUFFICIENT_ACCESSIs the running user missing FLS/object perms?Grant perms OR run-in-system-mode (carefully)
Debug passes, prod failsRunning-user context mismatchPattern 5 — reproduce under real user profile
  1. Locate the failure. Get the fault notification email (confirm Setup → Process Automation Settings routes faults correctly); identify the flow, version, and failing element API name; open the flow in Flow Builder and navigate to that element (Ctrl+F by API name).
  2. Diagnose the root cause. Read the error type against the table above; run Debug mode with a representative record ID and step through variable values at the failing element.
  3. Fix the root cause. Correct null references, move elements out of loops, fix field references, or resolve the underlying validation/trigger issue.
  4. Harden for the next failure. Add a fault path to the previously-failing element so future errors surface a user-friendly message rather than a raw platform error.
  5. Ship and verify the fix. Test in sandbox with the same record scenario; confirm the currently-active version is the fixed version (activate intentionally, don't rely on deploy order alone).
  6. Post-mortem if production. Document root cause + fix in the team's incident log so similar failures diagnose faster next time.

Review Checklist

Salesforce-Specific Gotchas

  1. Flow fault emails go to the user who activated the flow, not the admin — By default, fault emails go to the flow's last modifier. Configure fault email routing in Setup → Process Automation Settings to send to an admin group instead.
  2. Multiple active flow versions can coexist — Only one version can be active at a time for a given API name. If the error email references version 3 but you fixed version 4, confirm version 4 is the active version.
  3. Debug mode does not trigger actual DML — The Debug run executes the flow logic but does not commit records. This means you cannot rely on debug to catch DML failures that only appear with real data volumes or trigger interactions.
  4. Debug mode bypasses Apex triggers — the flow sees a simplified transaction. Trigger-ordering bugs don't reproduce in debug.
  5. Flow Interview Log is the forensic trail — for production failures you can't reproduce, check FlowInterviewLog + FlowInterviewLogEntry via Setup or SOQL.
  6. Paused flows are a separate failure mode — FlowInterview in Paused status isn't an error but is often mistaken for one. Check status before assuming failure.
  7. Custom exception thrown by invocable Apex shows up as generic Flow error — don't assume the error message is the Apex exception; check the invocable's log separately.
  8. "Run flow as System Admin" in debug hides FLS issues — always test under the real user's profile before declaring the fix done.
  9. Managed-package flow errors are opaque — element names are visible but internals aren't. File a case with the package vendor; don't try to patch the managed flow.
  10. Error email rate-limiting — orgs that fire thousands of flow errors per hour may see emails suppressed silently. Check FlowInterviewLog counts, not just email volume.

Proactive Triggers

Surface these WITHOUT being asked:

Output Artifacts

ArtifactDescription
Root cause analysisElement name, error type, variable that failed, triggering scenario
Fix recommendationSpecific change to make in Flow Builder with rationale
Fault path handler configurationScreen text or action to show when the fault path fires
Post-mortem entryRoot cause + fix + prevention for the team's incident log

Package files