elastic/elasticsearch · error · IllegalArgumentException

field [{}] is null, cannot extract key-value pairs.

Error message

field [{}] is null, cannot extract key-value pairs.

What it means

Thrown by KeyValueProcessor when getFieldValue(path, String.class, ignoreMissing) returns null — the field exists but its value is null. KV extraction requires a non-null string. IllegalArgumentException; ignore_missing would have caused early return before this check.

Source

Thrown at modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/KeyValueProcessor.java:155

            if (fieldPathPrefix.isEmpty()) {
                keyPrefixer = val -> val;
            } else {
                keyPrefixer = val -> fieldPathPrefix + val;
            }
            String path = document.renderTemplate(field);
            if (path.isEmpty() || document.hasField(path, true) == false) {
                if (ignoreMissing) {
                    return;
                } else {
                    throw new IllegalArgumentException("field [" + path + "] doesn't exist");
                }
            }
            String value = document.getFieldValue(path, String.class, ignoreMissing);
            if (value == null) {
                if (ignoreMissing) {
                    return;
                }
                throw new IllegalArgumentException("field [" + path + "] is null, cannot extract key-value pairs.");
            }
            for (String part : fieldSplitter.apply(value)) {
                String[] kv = valueSplitter.apply(part);
                if (kv.length != 2) {
                    throw new IllegalArgumentException("field [" + path + "] does not contain value_split [" + valueSplit + "]");
                }
                String key = keyTrimmer.apply(kv[0]);
                if (keyFilter.test(key)) {
                    append(document, keyPrefixer.apply(key), valueTrimmer.apply(bracketStrip.apply(kv[1])));
                }
            }
        };
    }

    private Function<String, String> buildTrimmer(String trim) {
        if (trim == null) {
            return val -> val;
        } else {

View on GitHub (pinned to db6a809a66)

Solutions

1. Set "ignore_missing": true (this also covers null values via the early return).
2. Add an upstream processor that drops/fills null values for that field.
3. Fix the producer to never send null for the kv source field.

Example fix

// before
{"kv": {"field": "message", "field_split": " ", "value_split": "="}}
// after
{"kv": {"field": "message", "field_split": " ", "value_split": "=", "ignore_missing": true}}

String path = document.renderTemplate(field);
if (document.getFieldValue(path, String.class, true) == null) {
    if (!ignoreMissing) {
        // skip or set ignore_missing
    }
}

static boolean kvFieldNotNull(IngestDocument doc, String path) {
    return doc.getFieldValue(path, String.class, true) != null;
}

try {
    kvProcessor.execute(doc);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is null, cannot extract")) {
        // route or set ignore_missing
    } else throw e;
}

When it happens

Trigger: The field exists in the document but is explicitly null, and ignore_missing=false. Field exists but is null is distinct from field doesn't exist (1155).

Common situations: Source data explicitly sets field to null; upstream processor nullified it; schema permits null where string expected.

Related errors

• field [{}] is null, cannot loop over its elements.
• field [{}] is null, cannot process it.
• field [{}] is null, cannot join.
• field [{}] doesn't exist
• unsupported ECS compatibility mode [{}]

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