Handle Flow Errors with Fault Paths

Learning Objectives

After completing this unit, you’ll be able to:

• Identify common causes of unhandled faults.
  
• Use fault paths to handle flow errors.
  
• Use $Flow.FaultMessage to communicate a more detailed error message.
  

The previous badge, Flow Implementation I, is required (so that you can reuse its playground). You need the package installed and we don't cover that installation in this badge.

The Most Dreaded Error Message in Flows

If you’ve worked with screen and autolaunched flows in Salesforce, your users might have reported an error message that fills a flow creator’s heart with dread:

An unhandled fault has occurred in this flow

An unhandled fault has occurred while processing the flow. Please contact your system administrator for more information.

When Salesforce presents this error message, it means something in the flow didn’t work… but the message doesn’t say what didn’t work. To make things more difficult, Salesforce shows this error message to the user running the flow, confusing the user with a vague error message that contains no details or instructions.

Unhandled faults can occur on any flow when it encounters an error, though its appearance may be different depending on the flow type. For record-triggered flows, it looks something like the following.

Regardless of its appearance, whenever an unhandled fault occurs, the flow stops running and the user must start over.

Here are a few of the most common causes of unhandled faults.

• The flow tries to create a record with a field that the running user can’t access.
  
• The flow tries to edit a record that the running user can’t access.
  
• The flow tries to create a record without setting a required field.
  
• The flow tries to edit a record by using an ID with the wrong number of characters.
  
• The flow tries to send an email to an invalid email address.
  
• The flow tries to do something that is blocked by a validation rule.
  

In this unit, we’re talking about the error messages shown to the user that runs the flow. For all flow errors, Salesforce also sends an email with details about the flow and the error. For more information, see Troubleshoot Flow Errors and Select Flow and Process Error Email Recipients in Salesforce Help.

An Ounce of Prevention

Don’t worry, there’s good news! You can prevent almost every occurrence of this error message by taking certain steps before you deploy your flow. We’re talking about another developer concept: error handling.

Error handling is the practice of controlling how errors affect your users and your automation. For example, validation rules are a form of error handling. You create a validation rule when you anticipate your users doing things they shouldn’t and want to show a specific error that specifies what the user should do instead. In flows, you can add elements that capture details about what went wrong and present that info to users, giving your users more information than the unhelpful “An unhandled fault has occurred” message. Both practices provide better guidance to users, and therefore a better user experience.

To deal with most unhandled fault errors, use a Flow Builder feature called fault paths. A fault path is a secondary path on the Flow Builder canvas that runs only if its source element encounters an unhandled fault. Instead of showing the “unhandled flow has occurred” error, the flow then runs along the fault path instead of the main path. It’s a great place to put elements that give more details about the error that occurred.

You can add a fault path to Get Records, Create Records, Update Records, Delete Records, and Action elements.

Show a Better Error Message with $Flow.FaultMessage

Salesforce handles flow errors differently for each flow type. Let’s look at a screen flow as an example. Pyroclastic, Inc. has a simple flow in their org that guides salespeople through creating a simple opportunity. However, users running this flow sometimes encounter the “unhandled fault” error message, so we’ll update the flow to provide more error details.

Because this is a screen flow, use a screen element in the fault path to display the $Flow.FaultMessage global variable.

1. Open the Guided Opp Create flow.
   
2. Click the Create Opportunity element.
   
3. Select Add Fault Path.
   
   
4. On the fault path, click .
   
5. Select Screen.
   
6. For Label, enter Fault Screen.
   
7. In the Components sidebar, select Display Text to add a Display Text screen component to the screen canvas.
   
8. For the screen component’s API Name, enter FaultText.
   
9. In the Insert a resource field, select $Flow then select FaultMessage.
   The $Flow.FaultMessage global variable provides a detailed error message. This message can be a bit technical, but it gives some important information that can be used to troubleshoot what went wrong.
   
10. In the rich text field, start a new line after {!$Flow.FaultMessage} and add this text:
    

    Name: {!oppVar.Name}
    Stage: {!oppVar.StageName}
    Close Date: {!Close_Date}
    Account: {!oppVar.AccountId}

    This text block displays details about what the user entered on the screen. (Because Name, Stage and Account are record fields, their values are stored in their record variable.) These details might help to identify what went wrong.
    
    
11. Click Done.
    
12. Save the flow.
    

Verify the Fault Message

Let’s run the flow with the Debug button to see how the fault path’s screen looks.

1. Click Debug.
   
2. In the Debug flow window, click Run.
   
3. Enter this data:
   
   • Opportunity Name: UA Generators
   • Stage: Prospecting
     
   • Close Date: (remove the default date, leaving Close Date blank)
     
   • Account Name: (type University and then select University of Arizona)
     
     
4. Click Next.
   Opportunities always require the Close Date field, so deleting the close date should cause the flow to error and head down the fault path.
   
   

The fault message gives enough detail to solve the problem: The Close Date field is required by Salesforce, so require the field on the screen as well.

It’s common to have multiple flows in an org that have the same elements in their fault path. For example, many of your screen flows might need fault paths that each have a single Screen element that displays $Flow.FaultMessage. If that sounds like your org, consider creating a dedicated Autolaunched flow that contains only the fault path’s elements, and call that Autolaunched flow as a subflow in your many screen flows. This shortcut saves time and effort when you create a flow.

Resources

• Salesforce Help: Customize What Happens When a Flow Fails
• Salesforce Help: Troubleshoot Flow Errors