Flow Interview Debugging

Flow Interview Debugging

Flow failures are quiet by default. The platform sends one email to one person — the user who last modified the flow — and writes nothing you can report on. If that person has left, or the flow runs asynchronously where no user is on screen, the failure leaves no trace at all beyond the record that did not get created.

This skill covers two jobs that usually arrive together. The first is triage: given an error email or a user complaint, find the element, the version, the data, and the running user that produced the failure. The second is instrumentation: change the flow so the next failure answers those questions without an investigation.

Recommended Workflow

1. Fix the notification path before anything else. Setup → Quick Find Automation → Process Automation Settings → set Send Process or Flow Error Email to = Apex Exception Email Recipients, then maintain that list under Setup → Apex Exception Email. Route it to a monitored alias, not an individual. Note that these emails contain the interview's data, including user-entered values — scope the alias accordingly.
2. Read the error email in order: element, status code, version, GUID, user. Error element <Name> (<Type>) names the failure point; the status code says whether it is data, contention, or a downstream trigger; Version: tells you which version to open (often not the one Flow Builder shows by default); Flow Interview GUID is the join key; Current User tells you whose permissions applied.
3. Reproduce in the debugger for the synchronous path only. Flow Builder → Debug. Iterate with roll-back on; do a final pass with roll-back off so commit-time and downstream automation actually run. For screen flows, debug as a low-privilege persona, not as yourself.
4. Observe the async path where it lives. Scheduled-path entries queue on Setup → Environments → Monitoring → Time-Based Workflow. Interview state lives on Setup → Paused And Failed Flow Interviews. The debugger reaches neither.
5. Instrument every fallible element. Put a fault connector on every DML, Action, and Subflow element, and point it at a Create Records that writes $Flow.FaultMessage, $Flow.InterviewGuid, the element name as a literal, the record Id, and the running user to a custom log object.
6. Decide per fault path whether the interview should continue. If the business outcome did not happen, end the path — in a record-triggered flow use the Custom Error element so the transaction rolls back and the user is told, rather than committing a half-finished state.
7. Close the loop with a threshold. Report on the log object, alert on a rate change, and review the Paused And Failed Flow Interviews page on a cadence.

Key Considerations

The fault connector is narrower than people expect. It fires on platform exceptions — an invalid reference, an object or field the running user cannot access, a governor breach. It does not fire when a Get Records matches zero rows, because zero rows is a successful query. "Not found" is a Decision, not a fault path.

$Flow.FaultMessage is only populated inside a fault path, and only until something else faults. Read it in the first element after the fault connector.

There is no global variable that reports which element faulted. The error email carries it; the interview does not. Pass the element name in as a literal at each fault-handler call site, or accept that a shared handler produces unattributable log rows.

$Flow.InterviewGuid is the only reliable join between an error email and a log row. Timestamps collide under bulk load and one record can be touched by several interviews in a transaction. Store the GUID as an indexed External ID.

Governor errors are transaction-wide, not flow-wide. Too many SOQL queries: 101 means the whole transaction spent 100 queries, and an Apex trigger or a second flow on the same object may have spent most of them before your first element ran. Inventory the object's automation before optimizing the flow.

The 2,000-executed-elements limit was removed at API version 57.0. Diagnoses that invoke it on a modern flow are reasoning from retired documentation. The live ceilings are CPU time and the SOQL/DML governors.

Worked Examples (see references/examples.md)

• Route error emails off the last modifier — the Process Automation Settings change and its privacy trade-off.
• A fault path that produces a usable log row — the Flow XML, including which fields carry the interview GUID and the element name.
• Wrong vs right: fault path on a Get Records that returns nothing — the same flow built both ways.
• Debugging the path you cannot see — scheduled and async paths, and the Time-Based Workflow queue.
• Reading a flow error email without guessing — which line answers which question.

Common Gotchas (see references/gotchas.md)

• Error email goes to the last modifier — and silently moves every time someone saves the flow.
• Zero rows is not a fault — the "not found" branch off a fault connector is dead code.
• The debugger skips async and skips commit — two whole classes of failure are invisible in it.
• The email's version is not the version you have open — Flow Builder opens the latest, the failure was in another one.
• A fault path that rejoins the happy path — converts a loud failure into a silent partial commit.

Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)

• Fault connector on a Get Records to catch "no records found".
• A Screen element as the fault handler in a flow type that has no screen.
• Invented globals like $Flow.CurrentElement or $Flow.ErrorElement.
• "Send the error email to the flow owner" — not one of the platform's options.
• Attributing any limit error to the removed 2,000-element cap.

Related

• flow/fault-handling — the fault-path patterns this skill instruments.
• flow/flow-runtime-error-diagnosis — decoding a specific runtime error string.
• flow/flow-bulkification — when triage lands on a governor limit.
• flow/flow-versioning-strategy — when the failing version is not the current one.
• standards/decision-trees/automation-selection.md — when a flow keeps failing because the work was never a Flow problem.

Official Sources Used

• Select Flow and Process Error Email Recipients — https://help.salesforce.com/s/articleView?id=sf.flow_troubleshoot_error_email.htm&type=5
• Customize What Happens When a Flow Fails — https://help.salesforce.com/s/articleView?id=platform.flow_build_logic_fault.htm&type=5
• Flow Resource: $Flow Global Variables — https://help.salesforce.com/s/articleView?id=sf.flow_ref_resources_system_variables.htm&type=5
• Test or Troubleshoot Flows with the Flow Builder Debugger — https://help.salesforce.com/s/articleView?id=platform.flow_test_debug.htm&type=5
• Per-Transaction Apex Governor Limits — https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_gov_limits.htm

The full annotated list, including the release notes behind the currency claims, is in references/well-architected.md.