Flow Runtime Error Diagnosis

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:

• Obtain the fault notification email (if configured) — it contains the Flow API name, version, element name, and error message.
• Identify whether the flow is a Record-Triggered Flow, Auto-Launched Flow, or Screen Flow — the diagnostic steps differ slightly.
• Know the record ID or scenario that triggered the failure, if available. This allows running the debug mode on a specific record.
• Check whether the Flow has any fault paths configured — if not, errors bubble up to the user or send a fault email.
• Confirm which Flow VERSION is active — the fault email reports the version that failed, but fixes must go to the currently-active version.

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:

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

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:

• Does NOT commit DML (you can't catch failures that only appear with real data).
• Does NOT run actual Apex triggers on the object (the trigger framework is bypassed in debug).
• Does NOT send email alerts or Platform Events (actions are simulated).
• Does NOT fully simulate bulk (single interview only).

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

Recommended Workflow

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

• Fault notification emails are configured and routing to the admin inbox
• Fault path handlers added to all Get Records, Create/Update/Delete, and Subflow elements
• No Get Records or DML elements inside Loop elements (check for limit violations)
• Null checks added after Get Records where the variable is used in formulas or decisions
• Fix tested with the original failing record scenario in sandbox
• Flow version confirmed — ensure the active version is the fixed version
• Post-mortem recorded (root cause + fix + prevention)
• Cross-agent lookup done (field-impact-analyzer for schema errors; flow-analyzer for pattern issues)

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:

• Flow fault email recipient is inactive → Flag as Critical. Errors disappear silently.
• Repeated errors on same element over time → Flag as High. Recurring issue, not transient; root-cause needed.
• Fault email reports a non-active version → Flag as High. Version management confusion; deploy and activate discipline needed.
• Failing element has no fault path → Flag as High. Even after root-cause fix, add the fault path for future surprises.
• Error pattern "works in debug, fails in prod" → Flag as High. Running-user mismatch; Pattern 5 applies.
• UNABLE_TO_LOCK_ROW in Flow Interview Log > threshold → Flag as High. Concurrency problem, not a flow bug.
• Missing fault-email configuration at org level → Flag as Critical. All future flow errors will disappear silently.
• Post-mortem not documented after a production flow failure → Flag as Medium. Next incident will take as long to diagnose.

Output Artifacts

Related Skills

• flow/fault-handling — companion skill; prevents the errors this skill diagnoses.
• flow/flow-bulkification — when the error is a bulk-safety violation (SOQL/DML limit).
• flow/flow-debugging — setting up debug logs for Flow and trace analysis (diagnostic setup).
• flow/flow-testing — write a regression test after the fix so the issue doesn't recur.
• flow/record-triggered-flow-patterns — when the root cause is a pattern-level design flaw.
• apex/trigger-and-flow-coexistence — when Apex + Flow contention on the same object causes the error.