4.2.1. Pipeline Errors and the Fail Activity

💡 First Principle: The Fail activity provides controlled pipeline termination with custom error messages—like a circuit breaker that trips with a clear reason code. Instead of silent failures or generic errors, you get actionable information about what went wrong.

Scenario: A Lookup activity queries reference data that should always exist. If it returns empty, the pipeline should fail with a clear message indicating which reference data is missing.

Fail Activity Configuration

Visual: Fail Activity Pattern

Implementation Pattern

1. Add Lookup activity to query required data
2. Add If Condition to check for empty results
3. Add Fail activity in the True branch
4. Configure error message and code
5. Continue processing in False branch

Beyond the Fail activity:

• Retry settings (activity General tab): the retry count re-runs this activity, not the whole pipeline, after a retry interval that is either Fixed (30 seconds by default) or Increasing Delay (exponential back-off up to a maximum interval). The activity timeout defaults to 12 hours, up to 7 days. Retries suit transient failures such as HTTP 429 throttling, a network blip or a slow source timing out; a longer timeout or a fixed Wait activity retries nothing, and retries don't fix a wrong path or bad credentials. When a job that normally takes minutes times out after hours, check the source system (load, a maintenance window, locking) and the network path before raising the limit.
• Skipped is not an error. It means an activity's dependency condition was never met; for example, its predecessor failed, so its On success successor never ran.
• There is no Try-Catch activity. The "catch" is an On fail path. Put the notification there, using an Office 365 Outlook or Teams activity (or a Web activity that calls a webhook), and add a Fail activity when the run must still end as Failed.
• A handled failure can leave the run Succeeded. If a failed activity's On fail path completes and nothing else fails, the pipeline run can report Succeeded, so an alert that watches only for failed pipeline runs never fires for that pipeline.
• Alerting only past a failure threshold in a loop: inside a ForEach, route each Copy activity's On fail path to a logging step and an Append Variable that records the failed item; after the loop, an If Condition on that array's length raises the alert only when failures pass your threshold.

⚠️ Exam Trap: Logging errors without failing the pipeline allows downstream activities to continue with bad data. If a condition should stop execution, use the Fail activity—logging alone is insufficient.

Dependency conditions and ForEach failures:

• Cancelled is not Failed: a run stopped on request (e.g., by a user) has its own status. Which downstream activity runs next is decided by the dependency conditions On success, On fail, On completion and On skip (see 2.5.1).
• One failed ForEach iteration doesn't stop the others: with sequential = false, iterations run in parallel up to batchCount (in no guaranteed order); the rest still finish, then—unless the failure is handled by an On fail path—the ForEach and the pipeline report Failed.
• Per-item error handling: put the On fail path (e.g., to a logging activity) on the inner activity—it fires once per failed iteration. A failure path on the ForEach itself fires once.
• Make reruns idempotent: re-running the pipeline (or a retried parent) starts the ForEach from the first item again, so already-processed files are reprocessed unless each iteration records or moves what it has finished (archive folder, control table).