elastic/elasticsearch · error · FailProcessorException

<rendered message template>

Error message

<rendered message template>

What it means

Thrown by FailProcessor.execute as a FailProcessorException (a specialized ElasticsearchException). The fail processor is intentionally designed to halt pipeline execution with a user-supplied message template; this is its sole behavior. The message is mustache-rendered against the document, so the exception text is dynamic. The processor exists to support conditional pipeline failure (e.g. inside an 'if' that detects bad data).

Source

Thrown at modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/FailProcessor.java:43

 */
public final class FailProcessor extends AbstractProcessor {

    public static final String TYPE = "fail";

    private final TemplateScript.Factory message;

    FailProcessor(String tag, String description, TemplateScript.Factory message) {
        super(tag, description);
        this.message = message;
    }

    public TemplateScript.Factory getMessage() {
        return message;
    }

    @Override
    public IngestDocument execute(IngestDocument document) {
        throw new FailProcessorException(document.renderTemplate(message));
    }

    @Override
    public String getType() {
        return TYPE;
    }

    public static final class Factory implements Processor.Factory {

        private final ScriptService scriptService;

        public Factory(ScriptService scriptService) {
            this.scriptService = scriptService;
        }

        @Override
        public FailProcessor create(
            Map<String, Processor.Factory> registry,

View on GitHub (pinned to db6a809a66)

Solutions

1. Confirm the fail processor is intended to fire; if so, fix the document so it no longer matches the 'if' condition.
2. Tighten or correct the 'if' condition so only genuinely invalid documents trigger it.
3. Remove or comment out the fail processor if it was left from debugging.
4. Configure pipeline 'on_failure' to route failed documents to a dead-letter index instead of dropping them.

Example fix

// before - fires for any document missing the field, including valid optional cases
{"fail": {"if": "ctx.tenant_id == null", "message": "missing tenant"}}
// after - only fail when tenant was supposed to be set
{"fail": {"if": "ctx.source == 'billing' && ctx.tenant_id == null", "message": "billing record missing tenant"}}

// Tighten the fail processor condition so it only fires on intended cases:
{"fail": {"if": "ctx.doc_type == 'order' && ctx.order_id == null", "message": "order missing order_id"}}

// Pipeline on_failure lets you capture FailProcessorException and route instead of dropping:
{"on_failure": [{"set": {"field": "failure_reason", "value": "{{_ingest.on_failure_message}}"}}, {"index": {"index": "ingest-dlq"}}]}

When it happens

Trigger: Any pipeline containing a 'fail' processor whose 'if' condition evaluates true on the document. The 'message' option (a required field) is rendered and thrown verbatim.

Common situations: Intentional rejection of malformed documents (fail wrapped in an if that checks for required fields); validation pipelines that abort on policy violations; debugging leftover fail processors; condition expressions that match more than intended.

Related errors

• Unable to find pattern [{}] in Grok's pattern dictionary
• circular reference in pattern back [{}]
• Can not convert grok patterns to regular expression
• unsupported ECS compatibility mode [{}]
• Invalid MAC address format

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/17c6fcef083718f0. Report an issue: GitHub.