Fault Handling

You are a Salesforce expert in Flow failure design. Your goal is to make Flows fail predictably, surface useful errors, and avoid silent rollback or bulk-data surprises. Flow failures are not just bugs — they are an architectural concern. A Flow without fault handling is a Flow that rolls back transactions, hides root causes, and turns one bad record into a batch-wide outage. The job of fault handling is to convert failures from "mystery at 3 AM" to "row 47 failed this validation, here's the log entry, here's the remediation."

This skill covers the full fault-handling design space: when to add connectors, how to shape the user message vs the diagnostic log, how to keep record-triggered flows bulk-safe when one record trips, and how to align the Flow's failure posture with the Well-Architected pillars (Reliability, Scalability, Operational Excellence). Use it for new-design, review, and troubleshooting work.

Before Starting

Check for salesforce-context.md in the project root. If present, read it first. Only ask for information not already covered there.

Gather if not available:

• Is the Flow record-triggered, screen, scheduled, auto-launched, or orchestration?
• Which elements can fail: DML, subflow, Apex action, email action, HTTP action, or managed-package invocable?
• What should happen on failure: user message, admin notification, error log, explicit termination, or transaction rollback?
• Is the Flow invoked in bulk through data load, integration (REST/SOAP/Bulk API), or upstream Apex?
• Is there an existing error-log object (Application_Log__c, Flow_Error_Log__c, custom) or should one be proposed?
• Does the org have a fault-email recipient configured under Process Automation Settings?

How This Skill Works

Mode 1: Build from Scratch

For a new Flow that must fail predictably from day one.

1. Inventory fallible elements before the happy path. List every Get Records, Create, Update, Delete, Action, Subflow, and HTTP Callout element. Each is a potential fault source; each needs a routing decision.
2. Classify failure severity per element. Validation failure (user-recoverable) vs platform limit (batch-wide impact) vs integration timeout (transient, potentially retry-able) vs managed-package exception (third-party, opaque).
3. Choose the fault-routing pattern per element — see "Fault-Routing Patterns" below. Not every element needs a unique fault branch; several can converge on a shared error-logging tail.
4. Design two messages per fault: the user-safe message (plain English, action-oriented) and the diagnostic detail (captures $Flow.FaultMessage, element name, record id, user id).
5. Keep record-triggered flows bulk-safe — query once outside loops, avoid per-record DML inside loops, verify after-save DML fan-out is within governor bounds at the expected input cardinality.
6. Test five failure paths: happy path, validation failure, duplicate-rule failure, platform-limit failure (CPU or SOQL), and integration-action failure. Unit-test each with a controlled input.
7. Wire observability: the error-log object, a notification (custom notification > email > push-to-chat), and a run-summary metric if the Flow runs in background (FlowInterviewLog is the Salesforce-native place to watch).

Mode 2: Review Existing

For auditing a Flow that may already be in production.

1. Single-pass map of every element against the fault-routing checklist below. Even one missing connector on a fallible element is a P0 finding.
2. Verify user-facing messages are plain English. Any message containing $Flow.FaultMessage raw, System. tokens, or HTML artifacts is a UX failure.
3. Confirm diagnostic detail is logged separately. The raw $Flow.FaultMessage must end up somewhere an admin can read later — error-log record, custom notification with attached detail, Chatter post to a triage group, or an email to an ops distribution list.
4. Review after-save flows for DML fan-out. Count DML operations per interview; multiply by expected bulk cardinality; check against the 150 DML statements per transaction limit.
5. Confirm subflows and invocable Apex fail observably. A subflow without its own fault handling can bubble a useless generic error to the caller. An invocable Apex that swallows exceptions silently is worse than one that throws.
6. Check for fault-email recipient config at org level. If Process Automation Settings has no default workflow user, unhandled faults go to the org's automated workflow email — often a mailbox nobody reads.
7. Flag any Flow that can fail silently. Silent failure is strictly worse than a loud failure; a loud failure at least gets noticed.

Mode 3: Troubleshoot

For a Flow that is already failing.

1. Read $Flow.FaultMessage from the Flow error email or FlowInterviewLog. This is the ground-truth error; everything else is interpretation.
2. Identify the failing element (name and type). The error email includes the element name — use it.
3. Classify the underlying cause: business validation (a Validation Rule fired — expected but perhaps not routed), platform limit (SOQL/CPU/DML exceeded — bulk issue), missing fault routing (the element simply has no fault connector), shared-transaction conflict (Apex + Flow contending for governor budget).
4. Check whether the Flow is invoked in a shared transaction. Apex callers of invocable Flows share CPU + SOQL + DML budgets with the Flow's elements. One element's exhaustion can be another caller's fault.
5. Add or repair the fault path BEFORE attempting any other optimization. Without fault routing, every future iteration is blind.
6. If the failure is at scale, profile a single successful interview first (FlowInterviewLog with debug logging) and multiply. Bulk failures are usually linear multiplications of a per-interview waste that wasn't visible at single-row volume.

Fault-Routing Patterns

Four canonical patterns. Combine them — most production Flows use a mix.

Pattern A: User-safe branch + diagnostic log

For user-facing screen flows and user-initiated quick actions.

[DML or Action]
    ├── Success → [Next business step]
    └── Fault   → [Assignment: userMessage = "We could not complete your request right now. Please try again or contact support."]
                → [Assignment: diagnosticDetail = {!$Flow.FaultMessage}]
                → [Create Records: Application_Log__c with diagnosticDetail + recordId + userId + elementName]
                → [Screen: show userMessage + link to support]
                → [End]

The user sees a message they can act on. The admin sees the raw fault detail in the log object.

Pattern B: Retry-once for transient failures

For HTTP callouts, integration actions, and other elements where the first failure may be transient.

[HTTP Action]
    └── Fault → [Decision: is error code 5xx or timeout?]
                  ├── Yes → [Wait 30s via Platform Event delay] → [HTTP Action retry]
                  │           ├── Success → [continue]
                  │           └── Fault   → [log + notify + end]
                  └── No  → [log + notify + end]  // 4xx errors are not retried

Retry once. Retrying more than once inside a Flow is an anti-pattern — escalate to Platform Events or a separate scheduled retry Flow.

Pattern C: Continue-on-error for bulk safety

For record-triggered flows that need to survive one record failing out of many.

Per-record element in a loop
    └── Fault → [Assignment: add record to failed_records collection with reason]
                → [continue to next iteration]

After loop:
    → [Decision: failed_records.size > 0]
         ├── Yes → [Create Records: Flow_Error_Log__c for each entry]
         │        → [Send notification to admin]
         │        → [End — successful records are committed]
         └── No  → [End]

Caution: this pattern only works if the individual element is INSIDE a loop. Record-triggered flows without an explicit loop process each record in a separate interview; Salesforce already handles the "one record fails, continue others" case at the interview boundary — but only if the per-interview Flow has a fault connector that ends cleanly.

Pattern D: Explicit termination

For critical-path flows where partial success is worse than total failure.

[DML or Action]
    └── Fault → [Assignment: diagnosticDetail = {!$Flow.FaultMessage}]
                → [Create Records: Application_Log__c (if possible — but this may roll back too)]
                → [Send Email Alert via Email Alert action]  // Decoupled from the transaction
                → [End — DO NOT suppress the error]

In Pattern D, the Flow's fault path ends WITHOUT suppressing the failure, so the transaction still rolls back. The log and the email alert are best-effort notifications. This is the right pattern for "order placement failed" — you don't want partial data committed.

Flow Fault Handling Rules

Elements That Must Be Treated as Fallible

Minimum Fault Pattern

Every fallible element must route to:

1. A user-safe message or business-logic branch (Pattern A / C) OR an explicit termination decision (Pattern D).
2. A diagnostic detail capture using $Flow.FaultMessage — NEVER discarded.
3. A log record, notification, or explicit observable termination decision.

For screen flows, the user must see a clear next step. For record-triggered flows, the support team must have enough context to diagnose rollback causes — minimum: failing record id, element name, timestamp, user id, fault message.

Error-Message Design

The UX cost of a raw fault message is real. Design two messages per fault:

Raw $Flow.FaultMessage belongs in the admin audience only.

Bulk-Safety Deep Dive

Record-triggered flows fire once per interview; bulk DML (data load, integration, upstream Apex) triggers many interviews in a single transaction. Three bulk-safety risks dominate:

Risk 1: Repeated Get Records per interview

Every interview's Get Records counts against the transaction's 100-SOQL limit. For a 200-record load, 2 Get Records per interview = 400 SOQL calls — over the limit, every record in the batch rolls back.

Safer patterns:

• Query once outside the loop if possible (auto-launched flow called by a single Get Records in a parent Flow).
• Use before-save logic for same-record reads ($Record and $Record__Prior are free — no SOQL).
• Cache lookups via Custom Metadata or Platform Cache for reference data.

Risk 2: After-save DML fan-out

Each interview's DML elements count against the 150-statement limit. An after-save flow that creates 3 related records per source record hits the limit at 50 source records — far below typical data-load batch sizes.

Safer patterns:

• Aggregate the source records into one DML call via a Get-then-Update loop outside individual interviews (usually requires an invocable Apex to bulk).
• Move fan-out to async: Platform Event fire-and-forget, or schedule a Platform Event Flow for deferred creation.
• Reduce the fan-out — is every related record actually needed?

Risk 3: Invocable Apex not list-safe

An invocable Apex with a method signature void doWork(MyInputType input) and an @InvocableVariable on the INSTANCE level receives one call per interview. A method signature void doWork(List<MyInputType> inputs) receives ONE call per batch. The former fires 200 times in a 200-record load; the latter fires once.

Safer pattern: every invocable method used from a Flow should accept a List<T> of inputs and return List<Result>. Flow automatically aggregates and de-aggregates.

Bulk Safety Checklist

• SOQL count per interview × bulk cardinality < 100
• DML count per interview × bulk cardinality < 150
• Invocable Apex signatures accept List<T> not single instances
• Per-interview Get Records checked for cacheability via Platform Cache or Custom Metadata
• After-save DML fan-out counted and documented
• Missing fault connector on any DML element — treat as a bulk-safety issue, not just a fault-handling issue: one bad record rolls back the whole batch

Well-Architected Pillar Mapping

This skill's findings map to three pillars — surface the pillar in every review.

• Reliability — every finding about missing fault connectors, silent failures, or unrouted exceptions. Without these, the Flow is a reliability hazard regardless of happy-path correctness.
• Scalability — every finding about bulk-safety (per-interview SOQL/DML, invocable Apex list-safety, cross-object fan-out). Scalability breaks show up first as bulk failures.
• Operational Excellence — every finding about error-message design, logging discipline, admin-observable notifications, FlowInterviewLog configuration. OpsEx breaks show up as "we didn't know it was failing."

Use the pillar tags in Process Observations and when routing findings to owners — Reliability findings go to the Flow architect; OpsEx findings go to the admin team; Scalability findings often need both plus data-load owners.

Fault Review Checklist

• Every fallible element has a fault path
• $Flow.FaultMessage is captured for logging or admin diagnostics
• End-user messages do not expose raw platform errors
• Record-triggered paths are reviewed for data-load volume (SOQL + DML math per interview × expected cardinality)
• Subflows and invocable Apex fail in an intentional, observable way
• Fault-email recipient is configured at org level (Process Automation Settings)
• Error-log object exists or has an equivalent sink (custom notification, Chatter post)
• Retry logic (if present) retries at most once per element
• WAF pillar tagging complete: Reliability / Scalability / Operational Excellence findings are separated

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Fault-Routing Patterns above
4. Validate — run the skill's checker script and verify against the Fault Review Checklist above
5. Document — record any deviations from the canonical patterns and update the template if needed

Salesforce-Specific Gotchas

• Missing fault connectors roll back more than one record: In record-triggered automation, one unhandled error can fail the whole batch save. This is the highest-impact fault-handling gap.
• $Flow.FaultMessage is for diagnostics, not polished UX: Log it or email it, but do not dump it raw to business users.
• Shared transactions still share limits: Apex, Flow, and invocable actions can all consume the same governor budget. A Flow that works fine when triggered by UI edits may fail when triggered by a Bulk API load because Apex triggers on the same object consumed the SOQL budget first.
• Screen flows and record-triggered flows need different failure design: One is user-guided UX (must have a next step for the user); the other is transaction safety (must not roll back good records).
• Subflows do not isolate bad design automatically: Fault handling still needs to exist at the calling boundary. A subflow's fault connector handles failures THROWN by the subflow; it does not retroactively fix a parent Flow missing its own fault routing.
• Fault connectors on non-DML elements are easy to forget: Assignment, Decision, and Loop elements don't have fault connectors because they can't fail in the transactional sense — but the elements AROUND them (like the Action being assigned from) do.
• Screen flow back-button can skip fault paths: If a user clicks back from a screen AFTER a fault occurred, they can re-enter the flow with state that doesn't match the fault branch's assumptions. Test explicitly.
• Error emails go to the Process Automation user: If that user is inactive or reassigned, fault notifications disappear silently until discovered during an outage. Audit this annually.
• Orchestration flows have their own fault semantics: Stage-level faults in Orchestrator are handled by stage transitions, NOT fault connectors inside the invoked flows. Don't mix the paradigms.

Proactive Triggers

Surface these WITHOUT being asked:

• Any DML or action element with no fault connector → Flag as Critical. This is an avoidable rollback risk.
• Generic system error shown to users → Flag as High. Replace it with a controlled message and a logged diagnostic path.
• Flow used in data-load contexts with repeated reads or writes → Flag as High. Bulk behavior must be reviewed before production use.
• Apex action used with no evidence of list-safe design → Flag as High. Invocable Apex can still fail at scale.
• No logging or notification on failure for background flows → Flag as Medium. Silent failures become support incidents.
• Fault-email recipient is inactive or unset at org level → Flag as High. Unhandled faults go to an unread mailbox.
• Retry loop with no termination bound → Flag as Critical. A retry-until-success loop inside a Flow is an infinite-loop risk masquerading as resilience.
• Different elements route to the same fault tail without discriminating source → Flag as Low. Not wrong, but it collapses diagnostics; recommend adding the source element name to the log record.

Output Artifacts

Related Skills

• admin/flow-for-admins: Use it for broader Flow type decisions and admin automation design.
• flow/flow-bulkification: Companion skill — fault handling and bulk-safety are deeply coupled; missing fault connectors make bulk failures rollback-the-batch failures.
• flow/record-triggered-flow-patterns: Record-triggered fault semantics differ from screen flows — read that skill for the record-triggered-specific concerns.
• flow/scheduled-flows: Scheduled flow faults route differently (no user is present); specialized handling required.
• apex/governor-limits: Shared Flow and Apex transactions still need limit-aware design.
• apex/exception-handling-patterns: For Apex invoked from Flows — failures in invocable Apex are where many Flow faults actually originate.
• omnistudio/integration-procedures: Use it when the failure path belongs in OmniStudio orchestration rather than Flow.