How to Debug a Salesforce Flow: Fix Common Errors

Key takeaways

• To debug a Salesforce Flow, run it in Flow Builder's Debug mode against a real record and read which element failed and what error text it returned.
• If only some users hit the error, debug as that user. Missing field access is one of the most common causes.
• Put a fault path on every element that reads or writes data, and store the fault message somewhere you can search.
• Control who receives flow error emails instead of switching them off. A silent failure costs more than a noisy one.

"An unhandled fault has occurred in this flow." Every admin has opened an email with that line, and it tells you almost nothing.

How to debug a Salesforce Flow is mostly a question of routine, not cleverness. My argument is simple: most admins lose hours because they debug backwards, from the error email into the flow, guessing. A fixed routine of reproduce, isolate the user, read the log and add a fault path gets you to the failing element in minutes. It also means the next failure tells you where it happened before you start looking.

How to debug a Salesforce Flow: the five-step routine

Debug in the same order every time, and don't touch the flow until you've seen it fail.

1. Reproduce the failure in a sandbox with Flow Builder's Debug button.
2. Re-run it as the user who actually hit the error.
3. If debug mode can't show it, capture a debug log.
4. Match the error text to its usual cause (table below).
5. Add a fault path so the next failure is logged, not mysterious.

Salesforce's own Flow Troubleshooting module on Trailhead follows the same logic: diagnose first, then fix. It takes about 45 minutes and is worth doing once.

Step 1: Reproduce it with Flow Builder's debug mode

Debug mode runs the flow against a real record and shows you, element by element, what happened.

Open the flow in Flow Builder and click Debug. For a record-triggered flow, pick a record that matches the failing case. For a screen flow, you'll go through the screens and enter values as a user would.

Three options matter:

• Rollback mode. Tick it so the debug run doesn't save changes. Without it, a debug run can create or update real records in whichever org you're in. Do this in a sandbox, never first in production.
• Show details of what is executed. This gives you the full trace: which elements ran, which path a Decision took and what each variable held.
• Run flow as another user. More on this next.

Read the debug panel from the top. The last element with a green tick is your neighbour of the problem. The element after it, the first red one, is the culprit. Its error message is the thing to search for or match to the table below.

Step 2: Debug as the user who hit the error

If the flow works for you and fails for a colleague, the cause is almost always who is running it, not what it does.

Salesforce's Trailhead unit on fixing access issues in a flow lists the usual suspects: the wrong field, the wrong variable, and object and field-level security for the running user. You, as an admin, can see every field. The sales rep can't.

Enable "Let admins debug flows as other users" in Process Automation Settings, then use the Run automation as another user option in the debug settings and pick the person who reported the problem. Screen flows normally run in the user's context, so their permissions apply. Record-triggered flows run in system context, so access problems there are rarer and more often point to a validation rule or bad data.

My take: Before you rewrite any logic, spend two minutes debugging as the affected user. In my judgement, a large share of "flow is broken" tickets are really "this profile can't see that field", and no amount of re-building the flow fixes that.

Step 3: Read the debug log when debug mode can't see it

Use a debug log when the failure only happens in real use, such as from an integration, a scheduled run or another automation.

Debug mode shows one flow in isolation. A debug log shows the whole transaction, including other flows, Apex triggers and validation rules firing around yours. Salesforce's help article How to Capture and Read Salesforce Debug Logs for Troubleshooting Flows, Apex, and Automations walks through setting this up.

The short version:

1. In Setup, open Debug Logs.
2. Add a trace flag for the user who triggers the failure.
3. Raise the Workflow log category so flow elements are recorded.
4. Reproduce the problem, then open the new log and search for the error.

If several automations touch the same object, the order they run in matters. Order of Execution in Salesforce, Explained Simply covers where flows sit among validation rules, triggers and workflow.

Common Salesforce Flow errors and what they usually mean

Most flow errors fall into a handful of causes, and the error text usually points straight at one of them.

Exact wording varies by release and by element, so treat this as a map, not a dictionary.

Error you see	Usual cause	First fix
An unhandled fault has occurred in this flow	An element failed and nothing caught it	Debug to find the element, then add a fault path
The flow failed to access the value for a variable because it hasn't been set or assigned	A null value, often a Get Records that found nothing	Add a Decision that checks the variable isn't null before using it
Too many SOQL queries: 101	A Get Records inside a loop, or several automations on one object	Move the query outside the loop and filter the collection instead
Too many DML statements: 151	Create, Update or Delete inside a loop	Add records to a collection in the loop, then do one DML after it
FIELD_CUSTOM_VALIDATION_EXCEPTION	A validation rule rejected the flow's save	Read the rule, then change the flow's values or the rule's criteria
Insufficient access or field not visible	The running user lacks object or field access	Debug as that user, then fix the permission set
REQUIRED_FIELD_MISSING	A Create or Update element doesn't set a required field	Set the field in the element

The 101 and 151 figures come from Salesforce's per-transaction limits of 100 SOQL queries and 150 DML statements, listed in the Apex governor limits reference. Flows share those limits with everything else in the transaction.

Null values deserve special mention. Salesforce's unit on fixing issues caused by a null value makes the point that a blank field can break a flow as surely as bad logic can. Assume any Get Records can return nothing, and decide what the flow does then.

When the flow throws no error at all

A flow that silently does nothing is usually failing its entry conditions, not failing at runtime.

This is the second most common complaint: no error, no email, no result. Check these in order:

• The flow's active version is the one you think it is.
• The trigger setting. "Only when a record is updated to meet the condition requirements" will not run again on a record that already met them.
• The entry conditions, tested against the actual record's values.
• Whether another automation changed the record first and took it out of scope.

Debug mode on a record-triggered flow shows whether the start criteria were met. That answers the question quickly.

Add fault paths so the next error explains itself

A fault path turns "something broke somewhere" into a logged message that names the element and the reason.

Salesforce's Trailhead unit Handle Flow Errors with Fault Paths teaches the pattern and the $Flow.FaultMessage global variable. Here's the setup I'd use:

1. Create a small custom object, for example Flow_Error_Log__c, with fields for flow name, element name, message and record ID.
2. On every Get Records, Create, Update, Delete and Action element, draw a Fault connector from the element.
3. Point each fault connector at a Create Records element that writes to the log object.
4. Map {!$Flow.FaultMessage} into the message field and {!$Record.Id} into the record ID.
5. Decide, deliberately, what the user sees next: a friendly screen message, a custom error, or nothing.

That last step is where teams get hurt. In a record-triggered flow, a handled fault can let the user's save succeed even though your automation didn't run. For some processes that's fine. For others, such as a discount approval, it means bad data sails through. The Custom Error element in record-triggered flows lets you stop the save with a clear message when it matters.

My take: A flow with no fault paths is a flow you've chosen to debug blind. I'd rather an admin spent an afternoon adding fault paths to the ten busiest flows than an afternoon each month chasing error emails.

How to stop flow error emails without hiding failures

Don't stop the emails by ignoring faults. Route them to the right people, then handle faults in the flow.

By default, unhandled flow faults generate an email, and it often lands with whoever last saved the flow. That's why the person who changed a flow once, years ago, still gets the alerts. Check who receives flow error emails in your org. The sources say they go to the admin who last modified the flow or to the Apex exception email recipients.

There are two honest ways to cut the noise:

• Handle the fault with a fault path. The error is then logged and, if you choose, reported once through a channel you control.
• Point error emails at a shared admin mailbox, not at an individual.

Switching alerts off entirely and hoping is the wrong answer. You'll find out about the failure from a sales director.

Common mistakes when debugging flows

• Debugging in production first. Use a sandbox, and tick rollback mode.
• Testing with one friendly record. Test with a record that has blank fields, since that's where nulls bite.
• Fixing the symptom. Adding a Decision to skip the bad record hides the data problem.
• Queries and DML inside loops. This is the usual route to the 101 and 151 errors.
• No naming discipline. Elements called "Update Records 3" make every debug trace harder to read. Name them for what they do.
• Testing as an admin only. You have access your users don't.

Once debugging is routine, it's also a skill worth practising before interviews. Salesforce Admin Interview Questions & Answers 2026 includes the sort of flow scenarios hiring managers ask. And if you're checking affected records with SOQL, Salesforce Workbench: Safe Use and Better Alternatives covers doing that without breaking things.

Try this week:

• Pick your busiest record-triggered flow and run Debug on it in a sandbox with rollback mode on.
• Re-run it as a real user from the team that complains most.
• Add a fault path to every data element and log {!$Flow.FaultMessage} to a custom object.
• Check who actually receives flow error emails, and change it to a shared mailbox.

If your org has dozens of flows nobody fully understands, get in touch and I'll tell you where I'd start.

Frequently asked questions

How do I debug a Salesforce Flow?

Open the flow in Flow Builder, click Debug, choose a real record or run through the screens, and read the debug panel to find the first element that failed. Use rollback mode and a sandbox so the test doesn't change live data. If it only fails for certain users, re-run as that user.

How do I debug a flow as another user?

In the Debug settings, choose the option to run the flow as another user and select the person who hit the error. This applies their object and field permissions, which is where many access errors show up. Salesforce's Trailhead unit on fixing access issues in a flow covers it.

Where can I see why a flow failed?

Start with the flow error email, which names the flow and the failing element. For the full picture, capture a debug log with a trace flag on the affected user. If you've added fault paths, check the error log you built, which is the most reliable option.

How do I stop Salesforce flow error emails?

Add fault paths so errors are handled and logged inside the flow, then review the email recipient settings in Process Automation Settings. Redirect alerts to a shared admin mailbox instead of removing them. Switching them off completely leaves you blind to real failures.

Why does my flow work in debug mode but fail for users?

Debug mode often runs with your admin permissions and a clean test record. Users may lack field access, or their records may have blank values your test didn't include. Debug as the affected user and test with the real failing record.