Salesforce Flow Debugging
A mechanic does not guess why an engine fails. The mechanic connects a tester, reads the signals, and finds the faulty part. Flow debugging gives admins the same ability. Salesforce lets you run a flow in a safe test mode, watch each element, and read the exact values at every step. Good debugging habits turn a confusing failure into a quick fix.
The Debug Button in Flow Builder
Flow Builder includes a Debug button at the top of the canvas. Clicking the button opens a panel where you supply test inputs.
- For a record-triggered flow, choose a real record to act as the trigger.
- For a screen flow, enter sample answers for the screens.
- For a schedule-triggered flow, run the flow against current matching records.
Two options change how the debug run behaves. Rollback mode lets the flow run without saving any changes to the database, so a test does not leave junk data behind. The Show Details option prints the value of each variable after every element.
Reading the Debug Output
The debug panel lists each element in the order Salesforce ran it. Green check marks show success, and red marks show failure. Expanding an element reveals the inputs it received and the outputs it produced.
Start ............................ OK
Get Records: Find Account ........ OK (1 record found)
Decision: Is Industry Tech? ...... OK (Outcome: Yes)
Update Records: Set Rating ....... FAILED
Error: REQUIRED_FIELD_MISSING
Required fields are missing: [Name]
The failed element and the error code point to the problem immediately. The example above shows an update that lacks a required value.
Common Flow Errors and Their Meaning
| Error | Typical Cause | Fix |
|---|---|---|
| REQUIRED_FIELD_MISSING | A required field has no value | Map the field in the Create or Update element |
| FIELD_CUSTOM_VALIDATION_EXCEPTION | A validation rule blocked the save | Satisfy the rule or adjust the flow data |
| INSUFFICIENT_ACCESS_OR_READONLY | The running user lacks permission | Grant access or run the flow in system context |
| Too many SOQL queries: 101 | A Get Records element sits inside a loop | Move the query outside the loop |
| Null value in formula | A Get Records element found nothing | Add a Decision that checks for null |
Fault Paths
A fault path is a connector that handles failure. Any element that touches data, such as Create Records or Get Records, offers a Fault connector. When the element fails, the flow follows the fault path instead of crashing.
Update Records ----Success----> Continue flow
|
+------Fault------> Create Records: Error Log
|
v
Send Email Action to Admin
A thoughtful fault path records the error message, which Salesforce exposes through the variable $Flow.FaultMessage. The admin receives a clear note, and users see a friendly message rather than a technical error screen.
Flow Error Emails
When a flow fails without a fault path, Salesforce sends an email to the person who last modified the flow. The message names the flow, the element, and the error. Teams should route that email to a shared mailbox so someone always reads it.
Paused and Failed Interviews
Setup includes a page named Paused and Failed Flow Interviews. The page lists flow runs that stopped, along with the failure reason. Admins resume a paused interview or delete one that no longer matters. Reviewing this list weekly reveals patterns that single error emails miss.
Debug Strategy That Works
- Reproduce the problem with one record.
- Run the flow in debug mode with Show Details enabled.
- Find the first red element and read the error text.
- Check the input values that the element received.
- Fix the cause and run the debug again.
- Test with a batch of 200 records to catch limit problems.
- Activate the new version and monitor the following runs.
Best Practices
- Label elements with descriptive names, such as Get Primary Contact, so the debug list reads like a story.
- Add Decision elements that guard against empty results.
- Test in a sandbox before editing an active production flow.
- Save a new version for every change, which provides an easy rollback.
- Keep a short log object that captures flow name, record Id, and error message.