elastic/elasticsearch · error · IllegalArgumentException

field [{}] is null, cannot join.

Error message

field [{}] is null, cannot join.

What it means

Thrown by JoinProcessor.execute when document.getFieldValue(field, List.class) returns null — the field is absent or null. Join requires a non-null list to concatenate. IllegalArgumentException; there is no ignore_missing option on this processor.

Source

Thrown at modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/JoinProcessor.java:57

    }

    String getField() {
        return field;
    }

    String getSeparator() {
        return separator;
    }

    String getTargetField() {
        return targetField;
    }

    @Override
    public IngestDocument execute(IngestDocument document) {
        List<?> list = document.getFieldValue(field, List.class);
        if (list == null) {
            throw new IllegalArgumentException("field [" + field + "] is null, cannot join.");
        }
        String joined = list.stream().map(Object::toString).collect(Collectors.joining(separator));
        document.setFieldValue(targetField, joined);
        return document;
    }

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

    public static final class Factory implements Processor.Factory {
        @Override
        public JoinProcessor create(
            Map<String, Processor.Factory> registry,
            String processorTag,
            String description,
            Map<String, Object> config,

View on GitHub (pinned to db6a809a66)

Solutions

1. Ensure the source field exists and is a list before join (add a set/split processor upstream).
2. Wrap the join processor in a conditional ("if": "ctx.containsKey('tags')") to skip documents lacking the field.
3. Fix the field path to match the actual document schema.

Example fix

// before
{"join": {"field": "tags", "separator": ","}}
// after
{"join": {"field": "tags", "separator": ",", "if": "ctx.tags != null"}}

if (!doc.hasField(field) || doc.getFieldValue(field, List.class) == null) {
    // skip or set field to empty list
}

static boolean canJoin(IngestDocument doc, String field) {
    return doc.getFieldValue(field, List.class) != null;
}

try {
    joinProcessor.execute(doc);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is null, cannot join")) {
        // route to dead-letter or set default
    } else throw e;
}

When it happens

Trigger: Join processor configured on a field that does not exist or is null in the incoming document.

Common situations: Source data without the expected array field, upstream processor removed the field, or field path typo.

Related errors

• field [{}] is null, cannot loop over its elements.
• field [{}] is null, cannot process it.
• field [{}] is null, cannot extract key-value pairs.
• unsupported ECS compatibility mode [{}]
• field [{}] is null, cannot parse.

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