Home / flow / flow-debugging

flow-debugging

Use when diagnosing a Flow that does not run, runs but produces wrong results, fails silently, or shows an unexpected fault email.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Operational Excellence
• Reliability

• flow-debugging
• debug-mode
• flow-interview-log
• fault-email
• record-triggered-flow
• flow-test-suite
• debug-log
• trace-flag
• workflow-log-category

Open the skill folder on GitHub

Flow Debugging

This skill activates when a practitioner needs to diagnose why a Salesforce Flow is not running, is producing wrong results, or is failing with an error.

This skill owns the method, not the surfaces. The method is six steps, and each one has a documented artefact behind it:

reproduce → capture (which trace-flag level yields which FLOW_* events, without truncation) → read the log (event sequence, element boundaries, value assignments, limit usage) → localise (element name; fault vs error vs limit) → fix → prove with a FlowTest

Neighbouring skills own the surfaces this method points at, and this skill does not repeat them:

Before Starting

Gather this context before working on anything in this domain:

Questions to Ask Before Configuring

What a proper configuration adds over just doing it: a capture rig that is scoped to one user, set to the one category and level that actually emits FLOW_* element events, and expired on purpose — so the log you read is complete, attributable, and reproducible by a FlowTest afterwards, instead of a truncated org-wide dump that answers a question nobody asked.

Core Concepts

The Two Failure Events, and Why the Level You Pick Decides What You See

Every flow failure surfaces as one of two debug events, and they log at different levels:

The levels run "from lowest to highest… NONE, ERROR, WARN, INFO, DEBUG, FINE, FINER, FINEST" and are cumulative (apexdev.txt L38389–L38403). ERROR therefore does not include WARN. A flow that handles its faults properly logs nothing at Workflow=ERROR.

references/metadata-examples.md §2 carries the full event table, the level matrix, and an annotated excerpt of the sequence a caught fault produces.

The Capture Is a Tooling API Object, Not Metadata

Trace flags are set "in the Developer Console or in Setup or by using the TraceFlag and DebugLevel Tooling API objects" (apexdev.txt L39543–L39546). They have no Metadata API type, so they cannot be deployed in package.xml and cannot be version-controlled with the flow. apex/debug-and-logging owns the general mechanics; the flow-shaped configuration — Workflow: FINER, everything else NONE — is in references/metadata-examples.md §3.

With no active trace flag, the defaults apply, and they include WORKFLOW: INFO (apexdev.txt L39553–L39560). At INFO you get interview start and end and no element events at all.

Debug Runs in Flow Builder

Flow Builder's Debug button runs the flow in the current org, showing input values, branch outcomes and element results, with options to run as another user, set variable values, and supply the triggering record's field values.

UNVERIFIED (2026-09-05): the Debug window, its "Run as a different user" and "Roll back changes after the debug run" options, and the per-element "Show Details" panel are documented only on help.salesforce.com, which cannot be fetched. None of these appears in api_meta.txt, apexdev.txt or object_reference.txt. Everything this skill asserts about the log is grounded; treat the Debug window's behaviour as field knowledge and verify each option in the org before relying on it — particularly the rollback checkbox, which governs whether a debug run writes real data.

A debug run and a captured log answer different questions. The debug run shows what happens now with values you chose. The log shows what happened then with the values the platform actually had. When a bug is data-dependent, only the second one can find it.

FlowInterview vs FlowInterviewLog

These are different objects with different scopes, and conflating them wastes more time in this domain than any other single mistake.

The queries for all three, plus FlowRecordRelation, are in references/metadata-examples.md §4.

Reproducing a Fault Deterministically

FlowTest is the artefact that turns "it failed once in production" into a repeatable check: "before you activate a record-triggered, autolaunched, or Data Cloud-triggered flow, you can test it to verify its expected results and identify flow run-time failures" (api_meta.txt L73961–L73962). The HasError comparison operator (API 64.0 and later, api_meta.txt L74203) is what lets a test assert that a failure did happen.

Test points can only be placed at Start and Finish (api_meta.txt L74139–L74147), so a FlowTest proves that the flow failed and the log proves where. You need both. flow/flow-testing owns strategy; §5 of references/metadata-examples.md has the two tests this method needs.

Common Patterns

Mode 1: Build Debug Into the Flow From the Start

When to use: Authoring a new flow or adding significant logic to an existing one.

How it works:

1. Give every element a descriptive label. The element name is what

   FLOW_ELEMENT_BEGIN / _END / _FAULT print (apexdev.txt L38768, L38774, L38792) — Decision_2 in a log at 2am tells you nothing.

2. Set interviewLabel on the flow. It is the only human-readable handle on

   FlowInterview.InterviewLabel (object_reference.txt L139951) and on the paused interviews list. A flow with waits or scheduled paths and no interviewLabel produces an untriageable queue.

3. Add a fault connector to every fault-capable element and capture $Flow.FaultMessage

   into a durable log record. flow/fault-handling owns the route design; this skill needs it to exist so the log emits FLOW_ELEMENT_FAULT rather than FLOW_ELEMENT_ERROR.

4. Write one FlowTest for the happy path and one for the most likely failure, using

   HasError for the second.

5. Run the checker before every deploy: python3 scripts/check_flow_debugging.py --manifest-dir <src>.

Why not the alternative: adding debuggability after the incident costs more than adding it during authoring, and the incident is exactly when you cannot afford it.

Mode 2: Diagnose a Flow That Is Not Running

When to use: A record-triggered flow is expected to fire on save but nothing happens — no changes, no email, no error.

How it works:

1. Confirm which version is actually active. If the repo contains a flowDefinition

   for this flow, its activeVersionNumber wins over the status in the flow files (api_meta.txt L73929–L73931). Read the version that is running, not the latest one.

2. Check the Start element: object, triggerType, recordTriggerType. Update will

   not fire on create — the enum values are Create, Update, CreateAndUpdate, Delete (API 50.0+), None (API 55.0+) (api_meta.txt L72448–L72457).

3. Verify the entry conditions and, critically, doesRequireRecordChangedToMeetCriteria:

   when true, "conditions evaluate to true only if the record didn't meet the required conditions before the triggering update but now meets the conditions after the update" (api_meta.txt L71320–L71322).

4. Check runInMode — DefaultMode, SystemModeWithSharing, SystemModeWithoutSharing

   (api_meta.txt L68374–L68390) — against the failing user's access.

5. Then capture. Set Workflow to INFO or above and look for

   FLOW_START_INTERVIEWS_BEGIN (apexdev.txt L38856). If it is absent, the flow genuinely never started and no amount of element-level logging will help.

Why not the alternative: reading flow logic before confirming the active version and the entry conditions is the most common time-wasting mistake in this domain.

Mode 3: Diagnose a Fault Email or Runtime Error

When to use: Someone receives a fault email, or users report an error on save.

How it works:

1. Find out who should have received it. On a default org

   (enableFlowUseApexExceptionEmail = false) it went to "the user who last modified the process or flow" (api_meta.txt L116961–L116967) — check with them before assuming no email was sent.

2. Take the element name from the email and hold it. That is your localisation until the log

   confirms it.

3. Set the capture rig (references/metadata-examples.md §3), reproduce, and pull the log.
4. Read in the order given in §2 of the same file: interview started? → fault or error line?

   → value assignments and rule details → limit usage.

5. Fix the underlying cause — data, permission, or field definition — then write the

   FlowTest that would have caught it, and only then re-activate.

Mode 4: Diagnose "It Ran and Did the Wrong Thing"

When to use: No error, no email, no fault. The flow completed and the data is wrong.

How it works:

1. This case needs FINER, not FINE. The two events that answer it are

   FLOW_RULE_DETAIL — "interview ID, rule name, and result" — and FLOW_VALUE_ASSIGNMENT — "interview ID, key, and value" (apexdev.txt L38847, L38896). Both are FINER+.

2. Walk the FLOW_RULE_DETAIL lines in order and find the first rule whose result is not

   what you expected. That decision is the branch point.

3. Walk back through FLOW_VALUE_ASSIGNMENT to the last write of each variable the rule

   reads. The value is printed; you do not have to infer it.

4. If a recordLookup returned the wrong record, FLOW_BULK_ELEMENT_DETAIL carries the

   record count (apexdev.txt L38724) — a count of 0 with a downstream null is the signature.

5. Encode the corrected expectation as a FlowTest assertion at Finish, so the wrong

   branch cannot come back silently.

Decision Guidance

Recommended Workflow

1. Pin the reproduction. Answer the Questions table above — specifically the failing

   record Id, the saving user, the flow type, and which version is active (checking for a flowDefinition that overrides status). Do not capture anything yet.

2. Choose the level from the fault-connector answer, then build the rig. Create the

   DebugLevel / TraceFlag pair from references/metadata-examples.md §3 — Workflow at FINER, every other category NONE, scoped to the one failing user, expiring within the hour. Confirm the header reads WORKFLOW,FINER before you trust the log.

3. Reproduce and pull the log, then read it in the fixed order in §2 of the same file:

   interview started → FLOW_ELEMENT_FAULT or FLOW_ELEMENT_ERROR → FLOW_RULE_DETAIL and FLOW_VALUE_ASSIGNMENT → *_LIMIT_USAGE. Match on event names, never on column positions.

4. Localise to one element and one category. Name the element, and classify the failure

   as caught fault, uncaught error, wrong branch, or limit. Hand off limit-shaped failures to flow/flow-bulkification and fault-route-design failures to flow/fault-handling rather than fixing them here.

5. If the log expired or the flow cannot be re-saved, fall back to §4: FlowInterview

   (InterviewStatus, Error, CurrentElement), FlowRecordRelation for the related record, and — for screen flows only — FlowInterviewLog / FlowInterviewLogEntry.

6. Fix, then prove it. Write the two FlowTest components from §5: one that reproduces

   the fault via HasError, one that proves the fix. Run python3 scripts/check_flow_debugging.py --manifest-dir <src> --strict and deploy in the order in §7.

7. Take the trace flag down. Delete it, or confirm its ExpirationDate has passed.

   Record what the log showed in templates/flow-debugging-template.md so the next person does not repeat the capture.

Review Checklist

Run through these before marking a debugging session complete:

• [ ] Confirmed the correct flow version is active, including any flowDefinition that pins it
• [ ] Verified trigger object, trigger event, and entry conditions match the expected firing scenario
• [ ] The log header was read and confirms the WORKFLOW level actually applied
• [ ] The failure was localised to a named element by a FLOW_ELEMENT_FAULT or FLOW_ELEMENT_ERROR line
• [ ] Classified as caught fault / uncaught error / wrong branch / limit — and routed to the owning skill if it is not this skill's fix
• [ ] Checked LogLength against the 20 MB ceiling before treating the log as complete
• [ ] Root cause is a data, permission or definition problem that was fixed — not a fault path added to hide it
• [ ] A FlowTest reproduces the original failure and fails on the pre-fix flow
• [ ] The checker script passes with --strict
• [ ] The trace flag is deleted or expired, and the org's log ceiling was not exhausted

Salesforce-Specific Gotchas

Twelve documented behaviours with guide line ranges are in references/gotchas.md. The three that most often decide whether a session succeeds:

1. Workflow at ERROR shows you nothing on a well-built flow. FLOW_ELEMENT_FAULT

   logs at WARNING and above; the levels are cumulative upward, so ERROR excludes it.

2. FlowInterviewLog is the screen-flow log. Zero rows for a record-triggered flow is

   the documented behaviour, not evidence the flow did not run.

3. The fault email default recipient is the last person who modified the flow. Not an

   admin, not an ops alias.

Output Artifacts

Reference Files

Related Skills

• flow/fault-handling — owns fault-route design, $Flow.FaultMessage capture, and rollback scope. Go there once the log tells you the fault path is missing or wrong.
• flow/flow-runtime-error-diagnosis — owns mapping a specific error code from a fault email to its cause. Go there when you have the message and need the meaning; come here when you need the message.
• flow/flow-error-monitoring — owns org-scale alerting, routing, thresholds and trend detection. Go there when the answer is "we should have known sooner", not "why did this one fail".
• flow/flow-interview-debugging — owns paused-interview state and instrumenting flows for triage.
• flow/flow-testing — owns test strategy, path matrices and coverage. This skill borrows exactly two tests from it.
• flow/flow-governance — owns Flow.settings (including the error-email recipient setting), naming, versioning and retirement.
• flow/flow-bulkification — owns the fix when FLOW_*_LIMIT_USAGE is the finding.
• flow/record-triggered-flow-patterns — owns triggerType / recordTriggerType selection and the guide's narrower availability wording.
• apex/debug-and-logging — owns trace flags, ApexLog, log retention and log-size management as subjects in their own right; this skill only configures them for the Workflow category.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/flow-debugging-template.md
• scripts/check_flow_debugging.py