Deployments & DevOps

Salesforce flow error emails: how to read them, route them and fix the flow

By the orgadmin.ai team9 min read

Sooner or later every admin gets one: an email with a subject like Error Occurred During Flow "Update_Opportunity_Stage", a body that opens with An unhandled fault has occurred in this flow, and then several screens of element-by-element detail. Sometimes it is one email. After a data load it can be two hundred.

The email is more useful than it looks. This guide shows how to read it quickly, open the failed run in Flow Builder, decide who should actually receive these emails, and change the flow so the next failure is handled instead of being thrown at a user.

What the flow error email is telling you

Salesforce sends the email whenever a flow interview (one run of a flow) fails and the failing element has no fault path. According to Salesforce Help, it contains:

  • The error message. What went wrong, in Salesforce's words. This is the line that matters.
  • The flow name and version. Check the version number: an error from an old version means interviews are still running on it, often scheduled paths or paused screen flows.
  • Element details. Every element the interview ran, in order, with the values it assigned. The last element listed is usually where it broke.
  • A link to debug. Newer emails include Flow Error: Click here to debug the error in Flow Builder, which opens the failed interview (more on that below).

Read the email bottom-up. Find the element named in the error, then scroll back up through the assignments to see what values it was working with. Nine times out of ten the cause is visible right there: an empty variable, a record that was not found, or a field value that a validation rule rejected.

One warning before you forward the email to anyone: error emails include the data the flow was handling, including what users typed in. Salesforce notes that password fields in screen flows display in plain text. Treat these emails as sensitive.

The errors you will see most often

The wording varies, but most flow failures fall into a handful of groups:

What the email saysWhat it usually meansWhere to look
FIELD_CUSTOM_VALIDATION_EXCEPTIONA validation rule rejected the record the flow tried to saveThe validation rule named in the message; whether the flow sets every field the rule checks
REQUIRED_FIELD_MISSINGA Create or Update Records element left a required field blankThe element's field mapping, and whether the source variable was ever set
Missing required input parameterAn action (send email, Apex, subflow) received an empty inputThe input variable; usually a Get Records element earlier that found nothing
The flow failed to access the value for…because it hasn't been set or assignedA null reference, typically a field on a record variable that was never populatedAdd a Decision that checks the record is not null before using it
INSUFFICIENT_ACCESS_OR_READONLY / INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITYThe running user cannot see or edit the recordWhether the flow runs in user or system context; the user's permissions and sharing
UNABLE_TO_LOCK_ROWAnother transaction held the record (common during bulk loads and integrations)Timing and volume; usually transient
APEX_CPU_TIME_LIMIT_EXCEEDED / Too many SOQL queries: 101The transaction ran out of governor limitsElements inside loops, and every other trigger and flow on the same object

The last row deserves a note. Flows share governor limits with every Apex trigger, validation rule and other flow in the same transaction, so the flow named in the email is often just the one that happened to hit the ceiling. If the error only appears during bulk updates, look for Get Records, Create Records or Update Records elements inside a loop, and look at what else fires on that object.

Open the failed interview in Flow Builder

For many flows you do not have to reproduce the failure by hand. Salesforce saves failed flow interviews for screen flows, record-triggered flows, schedule-triggered flows and autolaunched flows that aren't triggered, as long as they were built in the free-form layout. The link in the email opens the saved interview in Flow Builder's debugger, so you can step through exactly what happened with the real values.

The saved interview is not always there, though. Salesforce Help lists when a failed interview is not saved:

  • the error was handled by a fault connector;
  • the flow is from a managed package and is not a template;
  • the failure happened after the interview was paused and resumed;
  • the failure happened inside an Apex test;
  • the flow is a standard flow, or its status is Draft or InvalidDraft;
  • the interview is over 1 MB, or more than 1 GB of failed interviews are already stored.

There are also volume caps: at most 100 saved failures per flow and 3,000 per org in 24 hours, and only one interview is saved for a batch of up to 200 failures in the same transaction. Saved interviews are deleted after 14 days. So if a bulk load produced 200 emails, you will have one interview to debug, and if you wait three weeks, none.

When the interview is not available, fall back to the Flow Builder debugger with sample data (or Flow Test Mode if you have turned on the Winter '27 beta), and to a debug log for the user who hit the error.

Change who receives the emails

By default, the email goes to the user who last modified the flow. That is fine in a one-admin org. It is a problem when the last person to edit the flow was a contractor who has left, a consultant's integration user, or a developer who fixed a typo two years ago.

To change it:

  1. In Setup, enter Automation in Quick Find and open Process Automation Settings.
  2. Under Send Process or Flow Error Email to, choose Apex Exception Email Recipients instead of User Who Last Modified the Process or Flow.
  3. Save. Then open Apex Exception Email in Setup and add the people or the shared mailbox that should receive them.

You need the Customize Application permission to change the setting. Routing to a shared admin mailbox is usually the right call: failures stop disappearing into a former colleague's inbox, and the same list receives Apex exceptions, which often come from the same root cause.

Two quirks worth knowing. If the error happens in a subflow, the email goes to the author of the parent flow, but the subject names the subflow. And for a flow installed from a managed package (not a template), the email has no element details and goes to whoever installed the package, or to the Apex exception recipients.

Stop the failure reaching users: add fault paths

An unhandled fault means the user sees a generic error screen, or a record save fails with a message they cannot act on, and you find out by email afterwards. A fault path changes that. Any element that can fail (Get, Create, Update and Delete Records, actions, subflows) can have a fault connector: when the element fails, the flow follows that path instead of stopping.

A useful fault path does three things:

  1. Tells the user something they can act on. In a screen flow, route to a screen that explains what happened in plain words. In a record-triggered flow, there is no screen, so decide whether the save should still succeed.
  2. Keeps the technical detail. The {!$Flow.FaultMessage} global variable holds the error text. Write it, with the flow name, the record ID and the running user, to a custom log object or send it to the admin mailbox. Salesforce suggests logging errors to a custom object, and it is the only way to build a history of failures you can report on.
  3. Does not swallow the error silently. A fault path that just ends the flow hides real problems. Remember that handled errors are not saved as failed interviews, so your log is now the only record.

Do not add a fault path to every element blindly. Start with the elements that touch records or call external actions in your highest-volume flows, which is where most of the emails come from.

Make the next email easier to read

The best investment is cheap: name your elements properly. An email that says the error happened at Get_Records_3 tells you nothing; Get_Primary_Contact tells you where to look before you open the flow. Salesforce's own troubleshooting guidance makes the same point. Rename elements and variables when you next touch a flow, and add a description to each version saying what changed.

Find the flows that fail quietly

Error emails are reactive. They tell you about one failure, and only if they reach someone who reads them. They do not tell you which flows fail most, whether a failure is getting worse, or which users keep running into the same broken screen and quietly working around it.

That is the gap Flow Health in orgadmin.ai is built for. It reads the org's flow interview logs and shows, per flow, how many runs completed and how many failed, a real failure rate, the trend over the last 30 days to a year, which users hit the errors, and whose flows fail most. One honest limit: Salesforce writes those interview logs for screen flows, so record-triggered and autolaunched flows do not appear in the run charts. For those, the error emails and debug logs remain the source of truth.

When a failure needs a closer look, Debug Logs lets you pull the logs for the affected user and have the AI read up to five related logs together, pointing at the exception, the slowest queries and how close the transaction came to its governor limits. It reads and explains; it does not change your flows.

A short checklist

  • Read the error email bottom-up: error message, failing element, the values before it.
  • Use the debug link within 14 days, before the saved interview is deleted.
  • Send error emails to Apex exception recipients (a shared admin mailbox), not the last person who edited the flow.
  • Treat the emails as sensitive: they contain user-entered data.
  • Add fault paths to record-touching elements in high-volume flows, and log $Flow.FaultMessage somewhere you can report on.
  • Name elements so the next email explains itself.
  • Look at failure rates across flows, not one email at a time.

Try it on your own org

orgadmin.ai puts an AI assistant, a security review and 21 more tools on your Salesforce org. 14-day free trial, no credit card.

Start free trial