Skip to main content

Fail

Control Flow Elastic Compatible

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

FieldRequiredDefaultDescription
messageY-Error message to display. Supports templates using {{field}} syntax
descriptionN-Explanatory note for documentation
ifN-Condition determining when to fail
ignore_failureNfalseIf true, the failure is logged but processing continues
on_failureN-See Handling Failures
on_successN-See Handling Success
tagN-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"
warning

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.

note

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...

{
"field": "value"
}
fail:
- message: "Intentional failure"
- tag: "test"

produces an error message:

{
"error": {
"message": "Intentional failure",
"tag": "test"
}
}

Templates

Use document fields...

{
"user": {
"id": "12345",
"role": "guest"
},
"resource": "admin_panel"
}
fail:
- message: "User {{user.id}} with role {{user.role}} cannot access {{resource}}"
- if: "ctx.user.role != 'admin'"
- tag: "access_control"

to create detailed error messages:

{
"error": {
"message": "User 12345 with role guest cannot access admin_panel",
"tag": "access_control"
}
}

Conditionals

Document content can be used to state conditions...

{
"condition": true
}
fail:
- message: "Conditional failure triggered"
- if: "ctx.condition == true"
- description: "Fail when condition is true"

to fail when they are met:

{
"error": {
"message": "Conditional failure triggered"
}
}

Ignored Failure

Continuing despite failures...

{
"status": "warning"
}
fail:
- message: "Warning status detected"
- ignore_failure: true
- tag: "status_check"

logs the error without terminating:

{
"status": "warning",
"error": {
"message": "Warning status detected",
"tag": "status_check"
}
}