Fail
Synopsis
Intentionally fails the pipeline with a custom error message on a certain condition.
Schema
fail:
- message: <string>
- description: <text>
- if: <script>
- ignore_failure: <boolean>
- on_failure: <processor[]>
- on_success: <processor[]>
- tag: <string>
Configuration
Field | Required | Default | Description |
---|---|---|---|
message | Y | - | Error message to display. Supports templates using {{field}} syntax |
description | N | - | Explanatory note for documentation |
if | N | - | Condition determining when to fail |
ignore_failure | N | false | If true , the failure is logged but processing continues |
on_failure | N | - | See Handling Failures |
on_success | N | - | See Handling Success |
tag | N | - | Identifier for the failure point |
Details
This processor is particularly useful for validation with context-specific error messages, business rule enforcement, conditional pipeline termination, and debug and testing scenarios.
The message can include templates that reference document fields.
Typical uses:
-
Validation with Context
fail:
- message: "Invalid amount {{amount}} for currency {{currency}}"
- if: "ctx.amount <= 0" -
Access Control
fail:
- message: "User {{user.name}} lacks required permission: {{required_permission}}"
- if: "!ctx.user.permissions.contains(ctx.required_permission)" -
Data Quality
fail:
- message: "Field {{field_name}} exceeds maximum length of {{max_length}}"
- if: "ctx.field_name.length() > ctx.max_length"
Template fields must exist in the document or the processor will fail.
Complex conditions should be tested thoroughly as they can lead to unexpected failures.
Whenever possible, use templates to create clear, context-specific error messages: include relevant field values in error messages for debugging, use tag
for error categorization, and add description
to document failure conditions.
When ignore_failure
is set to true
, errors are still logged, but they don't stop the execution.
Examples
Basic Failure
Simple failure with static message... |
|
produces an error message: |
|
Templates
Use document fields... |
|
to create detailed error messages: |
|
Conditionals
Document content can be used to state conditions... |
|
to fail when they are met: |
|
Ignored Failure
Continuing despite failures... |
|
logs the error without terminating: |
|