To debug a Salesforce flow, open it in Flow Builder, click Debug, run it against a real record, and read the debug panel to see which element failed and why. If the failure only happens for certain people and the flow runs in user context, such as a screen flow, run the debug as that user. If it happens after the fact, start from the flow error email and the failed interview, then confirm the cause in a sandbox before you change anything.
That short version covers most flow problems. The rest of this guide gives you the full method: how to read an unhandled fault, which debug options to use for each flow type, how to track down permission and validation rule failures, and how to add a fault path so the next failure explains itself. Each step ends with a question you can answer, so you always know whether to move on or dig deeper. If you would rather hand the reading, comparing and editing to an AI client, the Salesforce Admin MCP Server from Cirra AI is covered near the end of this guide.
What debugging a flow means
A flow fails for one of two reasons. The logic does something you did not intend, or the platform refuses an action the logic asked for. Debugging is the work of finding out which one you have, and then finding the element where it happens.
Salesforce gives you four places to look:
- The Debug button in Flow Builder, which runs the flow and shows each element as it executes.
- The flow error email, which Salesforce sends when a flow fails with an unhandled fault.
- Debug logs in Setup, which record what the transaction did behind the scenes.
- Fault paths that you build into the flow, so errors get captured on purpose.
Most guides cover the first one and stop. The method below uses all four, in an order that saves time.
Step 1: Read the error before you open the flow
An unhandled fault means a flow element failed and the flow had no fault connector to catch it. The user sees a generic message, often "An unhandled fault has occurred in this flow." The useful detail goes to the flow error email.
Salesforce sends that email to the admin who last modified the flow, or to the Apex exception email recipients, depending on how your org is set up. It includes the flow name and version, the element that failed and the error message. It also includes a link that opens the flow in Flow Builder so you can debug it from there.
Read the email and write down three facts: the element name, the error code and the record that was being processed. The error code usually tells you which of these you are dealing with:
| Error you see | What it usually means | Where to look first |
|---|---|---|
| FIELD_CUSTOM_VALIDATION_EXCEPTION | A validation rule blocked the save | The validation rules on the object, and the message text |
| INSUFFICIENT_ACCESS_OR_READONLY | The running user lacks access to the record or field | Object permissions, field-level security, sharing |
| REQUIRED_FIELD_MISSING | The flow tried to save a record without a required field | The field mapping in the Create Records or Update Records element |
| UNABLE_TO_LOCK_ROW | Two transactions touched the same record at once | Other automation and integrations on the same object |
| Too many SOQL queries: 101 | A Get Records element sits inside a loop, or several automations stack up | The loop, and every other automation on the object |
| The flow failed to access the value for a variable because it hasn't been set or assigned | A variable was empty when an element used it | The Get Records element that should have filled it |
If the email names an element and a code, you may already have your answer. Check that cause directly before you run anything.
Question to answer before moving on: which element failed, and what did the platform say about it?
Step 2: Reproduce the failure with the debug panel
Open the flow in Flow Builder and click Debug. The options depend on the flow type.
For a record-triggered flow, you pick a triggering record and decide how the flow runs. The options that matter most:
- Rollback. Salesforce always runs record-triggered flow debugging in rollback mode, so the database changes are reversed when the run ends. Screen, autolaunched and scheduled flows have a "Run in rollback mode" option that you turn on yourself. A debug run without rollback saves its changes to real records.
- Skip start condition requirements. This forces the flow to run even when the record does not meet the entry conditions. It helps when you want to test the logic without finding a record that qualifies.
For a screen flow, the debug panel sits beside the running screens, so you can fill in a screen and watch the flow react. For autolaunched flows, you supply values for the input variables. Both flow types also offer "Run in rollback mode" and, for flows that run in user context, "Run flow as another user." That second option needs a one-time setting: in Setup, open Process Automation Settings and turn on "Let admins debug flows as other users."
Run the flow and read the panel from the top. It shows whether the start conditions were met, which elements ran, which branch each decision took and what value each variable held at each step. Switch on API names in the panel preferences if element labels are ambiguous, and turn on governor limit consumption to see how many queries and DML statements the run used. The clipboard icon copies the whole transcript, which is handy for a ticket or a teammate.
A flow that works in debug but fails in real use points to one of three things: the data differs, the user differs, or something else fires alongside it. The next steps cover each.
Question to answer: does the failure reproduce in debug? If it does, the panel shows you the element. If it does not, go to Step 3.
Step 3: Debug as the person who hit the error
Admins have broad permissions, so a flow that runs cleanly for you can fail for a sales rep. Trailhead walks through this exact situation: a screen flow works for the admin and breaks for a newly promoted user, and the cause turns out to be a missing permission rather than a flaw in the flow logic.
This step applies to flows that run in user context, such as a screen flow launched by the person. Record-triggered flows run in system context without sharing, so impersonating a user does not test that user's object permissions, field-level security or sharing for them. For a record-triggered flow, read the error email and debug logs, and check what the person's action triggered.
For a screen flow, turn on the Process Automation setting from Step 2, click Debug, check Run flow as another user and pick the person from the error email. Run it again. If the failure now appears, compare what that user can do with what the flow needs:
- Object permissions for every object the flow reads, creates or updates.
- Field-level security on each field the flow touches.
- Record access through ownership, sharing rules and role hierarchy.
- Permission sets that the flow's work depends on.
Also check how the flow runs. Running a flow as another user does not change its execution context. A flow can run in user context or system context, and system context offers a with sharing and a without sharing choice that treat record access differently. Switching a flow to ignore sharing hides the symptom and widens access, so treat it as a design decision and not a quick fix.
Question to answer: does the failing user have everything the flow touches?
Step 4: Check the data and the entry conditions
Many flow failures come from the record in front of the flow. Look at the record that triggered the error and check:
- Empty values. A Get Records element that finds nothing leaves its variable empty, and the next element that uses it fails. Add a Decision after every Get Records element to test whether anything came back.
- Entry conditions. For record-triggered flows, confirm the record met the condition you think it did. "Every time a record is updated and meets the condition requirements" runs on every later update that still meets the condition, while "Only when a record is updated to meet the condition requirements" runs only when the record changes from not meeting the condition to meeting it.
- Field types and formats. Text compared with a number, a date stored without a time and a picklist value that was renamed all produce quiet failures.
- Record type and status. Flows that filter on a record type or a status value stop matching when someone renames that value.
A SOQL query in the Developer Console or in a report gives you a quick look at the real values. The debug panel also prints the query parameters for Get Records elements, so you can see the filters the flow used.
Question to answer: was the data the flow received the data you expected?
Step 5: Find out what else runs on the same record
A flow rarely runs alone. Before-save flows run before validation rules, after-save flows run later in the save, and Apex triggers, other flows, workflow rules and processes can all fire on the same object. A failure that looks like it belongs to your flow may come from one of them.
Look for:
- Validation rules that your flow's update would violate. The error email will show the validation message when this is the cause.
- Other record-triggered flows on the same object. Open Flows in Setup, find every flow built on the same object and read the entry conditions for each.
- Apex triggers that update the same fields, which can send two automations into a loop.
- Duplicate rules and required fields that the flow's Create Records element does not populate.
If two automations update each other's fields, add an entry condition so the second one only runs when a relevant field changed.
Question to answer: could another automation or a validation rule be causing this?
Step 6: Use debug logs and governor limits for the hard cases
Some failures do not reproduce in the debug panel, especially those that depend on the volume of records, on scheduled paths or on integrations. For those, use debug logs.
- In Setup, open Debug Logs and add a trace flag for the user the flow runs as.
- Raise the Workflow log category, with FINE or higher as a common starting point, so flow activity appears in the log.
- Reproduce the problem, then open the log and look for the flow's start, the element that failed and any limit warnings.
Governor limits deserve a check whenever a flow touches many records. The two limits that trip flows most often are the 100 SOQL queries and the 150 DML statements allowed in one synchronous transaction. A Get Records or Update Records element inside a loop spends those limits one record at a time, so the same flow that passes with one record fails on a data load of two hundred. The fix is to move the element outside the loop: collect the records in a collection variable inside the loop, then run a single Update Records after it.
For scheduled paths and asynchronous work, look at Paused and Failed Flow Interviews in Setup, which lists interviews that did not finish.
Question to answer: does the failure depend on volume, timing or a limit?
Step 7: Fix it, add a fault path and test again
Once you know the cause, fix it in a sandbox, retest with the same record and the same user, and only then deploy through your normal process. Keep a record of what you changed: save the flow with a version description, and keep the previous version so you can switch back.
Then add a fault path so the next failure is easy to read. A fault path is a connector, drawn in red, that you can add to elements that work with data, Apex or subflows. When the element fails, the flow follows the fault path and you decide what happens.
A simple pattern that works well:
- Add a fault connector from the element that can fail.
- Create a record in a custom Flow Error Log object, or send an email to the team that owns the flow.
- Fill in the message from the flow's own context.
Here is a text template you can use as the message body. The $Flow.FaultMessage variable holds the error text and $Flow.InterviewGuid identifies the specific run:
Flow: Update Contact Department
Element: Update_Contact_Department
Record Id: {!$Record.Id}
Interview: {!$Flow.InterviewGuid}
Error: {!$Flow.FaultMessage}For screen flows, end the fault path on a screen that tells the user what to do next in plain words, so they do not see the generic message.
If your flow is record-triggered, build flow tests as well. A flow test runs the flow against test data and checks the result, which gives you a repeatable check each time someone edits the flow.
Question to answer: if this fails again, will you know within a minute where and why?
A quick debugging checklist
- Read the flow error email and note the element, the error code and the record.
- Debug the flow, with rollback mode on for any flow type where it is optional.
- For a flow that runs in user context, run the debug again as the user who hit the error.
- Check entry conditions and empty values.
- Look for validation rules and other automation on the same object.
- Review debug logs and limits if the problem depends on volume or timing.
- Fix in a sandbox, add a fault path and retest.
Where an AI client helps with flow debugging
Flow Builder's Debug button stays the place where a flow runs. The reading, comparing and editing around it is where an AI client saves effort, and that is where Cirra AI fits.
Cirra AI is the first commercial Salesforce Admin MCP Server. You connect a Salesforce org through OAuth, connect the AI client you already use, such as Claude, ChatGPT or Cursor, and describe the task in plain English. Cirra AI works as the connected user, within that user's permissions, and documents every change.
For flow debugging, that gives you a few practical moves:
- Ask the AI client to read an existing flow and explain its logic in plain English, which helps when you inherit a flow someone else built.
- Review a flow against best-practice checks, including whether fault paths cover the elements that need them.
- Query the data the flow works with, with SOQL, to check the values behind a failure.
- Check who has access to an object or field when you suspect a permission gap.
- Edit the flow logic once you have agreed on the fix, then review the change in a sandbox before it goes anywhere near production.
Cirra AI supports Salesforce Enterprise Edition and up, and Access Rules let an admin limit what the connection can read or change in each org. Our Salesforce flow automation page shows the flow types Cirra AI builds and edits, and the Salesforce Admin MCP product page lists what else the server covers. You can Start Free Trial and try it on a sandbox flow you already know well.
If flow upkeep is where your week goes, our piece on why debugging flows gets harder as they pile up looks at the scale problem behind it, and the Salesforce admins page shows how admins use Cirra AI across the rest of their work.
Frequently asked questions
How do I debug a Salesforce flow?
Open the flow in Flow Builder, click Debug, choose a record or enter input values, turn on rollback mode where it is optional and run it. The debug panel shows which elements ran, which path each decision took and the value of each variable, so you can find the element that failed.
What does "An unhandled fault has occurred in this flow" mean?
It means a flow element failed and the flow had no fault path to catch the error. Salesforce sends the details to the flow error email. Open that email, find the element and error code, then reproduce the failure in the debug panel.
Does debugging a flow change my data?
It can. A debug run that finishes without rollback mode saves its changes to real records. Record-triggered flows always debug in rollback mode, but for other flow types turn on "Run in rollback mode" in the debug options, and test in a sandbox when you can.
Why does my flow work for me but fail for another user?
Admins usually have broad access, so a flow can pass for you and fail for someone with fewer permissions. For a flow that runs in user context, such as a screen flow, turn on "Let admins debug flows as other users" in Process Automation Settings, then run the debug as the affected user and check their object permissions, field-level security and record access. Record-triggered flows run in system context without sharing, so running as another user does not apply that user's permissions to them; use the flow error email and debug logs instead.
Where do I find flow error emails and failed flow interviews?
Salesforce sends flow error emails to the admin who last modified the flow or to the Apex exception email recipients. For interviews that paused or failed, open Paused and Failed Flow Interviews in Setup.
What is a fault path in Salesforce Flow?
A fault path is a connector, drawn in red, that runs when a flow element fails. You can use it to log the error, notify the team that owns the flow or show the user a clear message. The $Flow.FaultMessage variable holds the error text.
Can an AI client debug a Salesforce flow for me?
An AI client connected to your org through Cirra AI can read a flow, explain its logic, review it against best-practice checks, query related data and edit the flow once you approve the fix. You still run and verify the result in Flow Builder, preferably in a sandbox.
