Salesforce Flow Debugging: Tools, Errors and a Checklist

To debug a Salesforce flow, open it 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 in read-only mode and flags the ones most likely to fail. See the free Salesforce flow audit and 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.

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.

1. Open the flow in Flow Builder and click Debug.
2. For a record-triggered flow, choose the record the flow should treat as the trigger.
3. Set the input values, if the flow is a screen flow or has input variables.
4. Turn on rollback mode. Salesforce then does not save the data changes the run makes (Trailhead, Debug Flows as Another User).
5. 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 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. In Setup, search for Process Automation Settings and turn on the option that lets admins debug flows as other users. Then pick the user in the debug panel and run again. Trailhead advises you 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. A save can fire Apex triggers, validation rules, other flows and roll-up summaries in one transaction. Flow Builder debug shows you only one flow.

1. In Setup, open Debug Logs and add a trace flag for the user who hits the error.
2. Set the log levels so the automation categories are detailed. Keep the other categories low, so the log stays small.
3. Reproduce the error as that user.
4. Open the log and search for FLOW_ lines, FATAL_ERROR and LIMIT_USAGE. Read upward from the error to find what started the chain.

If two flows or triggers update the same record, read the order of execution in the log. Our guide on Salesforce flow race conditions covers that case.

How do fault paths and error emails work?

A fault path is an optional branch you add to most data elements, such as Create Records, Update Records, Delete Records and Get Records. It runs when that element fails. 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:

1. Click the element, then drag its fault connector (the red line) to a new element.
2. Add a Create Records element that writes a log record, or a Send Email action to an admin.
3. Include $Flow.FaultMessage in the text. It holds the error message from the failed element.

Salesforce also sends an email with details of the flow and the error when a flow fails. You choose the recipients in Process Automation Settings. A Salesforce known issue reports that these emails can still go out when a fault path is in place, 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):

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 and 150 DML statements (data changes) (Salesforce Developers). A Get Records or Update Records element inside a loop is the usual cause. Move it outside the loop. See the governor limits entry and Salesforce's Apex governor limits for the current numbers.

What is a flow debugging checklist I can follow?

1. Read the error text. Note the element name and the record Id.
2. Check the flow's active version. You may be debugging an old one.
3. Reproduce the error in a sandbox with rollback mode on.
4. Run the debug as the user who hit the error.
5. Check field-level security and required fields for that user.
6. Check for validation rules and other automation on the same object.
7. Look for Get Records, Update Records or Create Records inside a loop.
8. If Flow Builder debug is clean, turn on a debug log and read the full transaction.
9. Add a fault path to the element that failed, with $Flow.FaultMessage in the message.
10. Test the fix, then deploy it. Watch the error emails for a few days.

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 a read-only scan first, you approve every change, sandbox first, rollback ready. Clientell AI asks before it changes anything in production. See privacy and security.

Try it in Clientell AI: "Scan my flows in read-only mode 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.

FAQ: 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 sends an email with details of the flow and the error. You choose the recipients in Process Automation Settings.

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 for this Salesforce flow debugging guide

• Trailhead, Debug Flows as Another User
• Trailhead, Handle Flow Errors with Fault Paths
• Salesforce Issues, flow error emails sent with fault connectors
• Xappex, Unable to Lock Row
• Salesforce Developers, Apex governor limits

Last updated: October 9, 2026