Salesforce flow debugging is the work of finding which element of a flow fails and why. Open the flow in Flow Builder and click Debug. Pick a test record, turn on rollback mode so nothing saves, and read the run step by step. For errors in production, use debug logs and fault paths.
Clientell AI, the AI Salesforce admin, reads your flows and the objects they touch. It flags the ones most likely to fail. Start with the free, read-only Salesforce flow audit or see how Clientell AI builds and fixes flows. The steps below work without any tool.
What are the ways to debug a Salesforce flow?
There are three layers. Use them in order.
| Layer | Where | Best for | Limit |
|---|---|---|---|
| Debug in Flow Builder | The Debug button in the flow | Logic mistakes in one flow | Tests one flow, not the whole transaction |
| Debug logs | Setup > Debug Logs | Order of execution, triggers, validation rules, limits | Needs a trace flag, and logs are long |
| Fault paths and error emails | In the flow itself | Failures in production | Only fires on elements you wire up |
How do I use Debug in Flow Builder?
The Debug button runs the flow from inside Flow Builder and shows each element, the values it read and the path it took.
- Open the flow in Flow Builder and click Debug.
- For a record-triggered flow, choose the record the flow should treat as the trigger.
- Set the input values, if the flow is a screen flow or has input variables.
- Turn on rollback mode. Salesforce then does not save the data changes the run makes (Trailhead, Debug Flows as Another User).
- Click Run and read the debug panel from the top. Find the first element whose output looks wrong.
Run it without rollback mode only in a sandbox (a test copy of your org). A debug run that is not rolled back changes real records.
How do I debug a flow as another user?
Many flows fail only for one profile, because that user cannot see a field or object. Go to Setup > Process Automation > Process Automation Settings and turn on Let admins debug flows as other users. Then pick the user in the debug panel and run again. Change the run context only when the flow's intended users need it (Trailhead).
When do I need debug logs instead?
Use debug logs when the flow is not the whole story. One save can fire Apex triggers, validation rules, other flows and roll-up summaries. Flow Builder debug shows you only one flow.
- Go to
Setup > Debug Logsand add a trace flag (a rule that turns logging on) for the user who hits the error. - Raise the Workflow category to a detailed level, so flow steps show up. Keep the other categories low, so the log stays small.
- Reproduce the error as that user.
- Open the log and search for
FLOW_lines,FATAL_ERRORandLIMIT_USAGE. Read upward from the error to find what started the chain. The log should name the failing flow and element.
If two flows or triggers update the same record, read the order of execution in the log. Our guide to flow race conditions covers that case.
How do fault paths and error emails work?
A fault path is an optional branch on a data element. It runs when that element fails. You can add one to Create Records, Update Records, Delete Records and Get Records. Without a fault path, an unhandled fault stops the flow, and the user sees a generic message (Trailhead, Handle Flow Errors with Fault Paths).
To add one:
- Click the element, then drag its fault connector (the red line) to a new element.
- Add a Create Records element that writes a log record, or a Send Email action to an admin.
- Include
$Flow.FaultMessagein the text. It holds the error message from the failed element.
Salesforce also emails the details of a flow error. The same settings page has a Send Process or Flow Error Email to field. It offers the user who last modified the flow or the Apex Exception Email recipients. Salesforce lists a known issue where these emails still go out when a fault path exists, so do not count on a fault path to silence them (Salesforce Issues).
What are the most common flow errors?
Trailhead lists these frequent causes of an unhandled fault (Trailhead):
| Cause | What to check |
|---|---|
| The running user cannot access a field | Field-level security on the field for that user's profile or permission set |
| A required field is not set | The Create or Update element for every required field on the object |
| An invalid email address | The value passed to the Send Email action |
| A validation rule blocks the save | The rule's error message in $Flow.FaultMessage |
Two more errors show up often in busy orgs:
- UNABLE_TO_LOCK_ROW. Two operations tried to write the same record at once, and one lost the lock. The locked record is often a parent, such as the Account when a child record updates (Xappex). Look for another flow, import or integration that touches the same parent.
- Governor limit errors. Salesforce caps what one transaction can do. In a synchronous transaction the cap is 100 SOQL queries (Salesforce Object Query Language, the language behind Get Records) and 150 DML statements (data manipulation language, meaning creates, updates and deletes) (Salesforce Developers). A Get Records or Update Records element inside a loop is the usual cause. Move it outside the loop. The glossary entry on governor limits has more.
What is a flow debugging checklist I can follow?
- Read the error text. Note the element name and the record Id.
- Check the flow's active version. You may be debugging an old one.
- Reproduce the error in a sandbox with rollback mode on.
- Run the debug as the user who hit the error.
- Check field-level security and required fields for that user.
- Check for validation rules and other automation on the same object.
- Look for Get Records, Update Records or Create Records inside a loop.
- If Flow Builder debug is clean, turn on a debug log and read the full transaction.
- Add a fault path to the element that failed, with
$Flow.FaultMessagein the message. - Test the fix, then deploy it. Watch the error emails for a few days. If the fix makes things worse, activate the previous flow version from the flow's detail page.
For design habits that prevent these errors, read Salesforce Flow Builder best practices and pitfalls. To remove flows you no longer use, see how to clean up Salesforce flows.
How do I check my flows for problems in Clientell AI?
The safe order is sandbox first, with rollback ready. Clientell AI asks before it changes anything in production. Read the security and privacy details.
Try it in Clientell AI: "Scan my flows and list the ones with no fault path or with Get Records inside a loop, with the fix for each."
Start the 14-day trial, no card needed.
Common questions about Salesforce flow debugging
Does the Debug button change my data?
It can. Turn on rollback mode and Salesforce does not save the changes the run makes. If you leave it off, the run changes real records, so use a sandbox.
Why does my flow work in debug but fail in production?
Debug often runs as you, an admin. The real user may lack field access, or another trigger or flow may fire in the same save. Debug as that user, then read a debug log.
Do I need a fault path on every flow?
Add one to every element that creates, updates, deletes or reads records. Without it, an error stops the flow and the user sees a generic message.
Who gets the flow error emails?
Salesforce emails the details of the flow and the error. In Setup > Process Automation > Process Automation Settings, choose between the user who last modified the flow and the Apex Exception Email recipients.
How do I find which flow caused an error?
Open the error email or the debug log. Both name the flow and the element. Then check that you are looking at the active version.
Sources
Salesforce documentation
- Debug Flows as Another User, Trailhead
- Handle Flow Errors with Fault Paths, Trailhead
- Flow error emails sent with fault connectors, Salesforce Issues
- Apex governor limits cheat sheet, Salesforce Developers
Industry research
Last reviewed October 2026
Last updated: October 22, 2026



