{"record":{"id":"b9907fcc9c25b27a","repo":"elastic/elasticsearch","slug":"field-is-null-cannot-extract-key-value-pairs","errorCode":null,"errorMessage":"field [{}] is null, cannot extract key-value pairs.","messagePattern":"field \\[(.+?)\\] is null, cannot extract key-value pairs\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/KeyValueProcessor.java","lineNumber":155,"sourceCode":"            if (fieldPathPrefix.isEmpty()) {\n                keyPrefixer = val -> val;\n            } else {\n                keyPrefixer = val -> fieldPathPrefix + val;\n            }\n            String path = document.renderTemplate(field);\n            if (path.isEmpty() || document.hasField(path, true) == false) {\n                if (ignoreMissing) {\n                    return;\n                } else {\n                    throw new IllegalArgumentException(\"field [\" + path + \"] doesn't exist\");\n                }\n            }\n            String value = document.getFieldValue(path, String.class, ignoreMissing);\n            if (value == null) {\n                if (ignoreMissing) {\n                    return;\n                }\n                throw new IllegalArgumentException(\"field [\" + path + \"] is null, cannot extract key-value pairs.\");\n            }\n            for (String part : fieldSplitter.apply(value)) {\n                String[] kv = valueSplitter.apply(part);\n                if (kv.length != 2) {\n                    throw new IllegalArgumentException(\"field [\" + path + \"] does not contain value_split [\" + valueSplit + \"]\");\n                }\n                String key = keyTrimmer.apply(kv[0]);\n                if (keyFilter.test(key)) {\n                    append(document, keyPrefixer.apply(key), valueTrimmer.apply(bracketStrip.apply(kv[1])));\n                }\n            }\n        };\n    }\n\n    private Function<String, String> buildTrimmer(String trim) {\n        if (trim == null) {\n            return val -> val;\n        } else {","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/KeyValueProcessor.java#L137-L173","documentation":"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.","triggerScenarios":"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).","commonSituations":"Source data explicitly sets field to null; upstream processor nullified it; schema permits null where string expected.","solutions":["Set \"ignore_missing\": true (this also covers null values via the early return).","Add an upstream processor that drops/fills null values for that field.","Fix the producer to never send null for the kv source field."],"exampleFix":"// before\n{\"kv\": {\"field\": \"message\", \"field_split\": \" \", \"value_split\": \"=\"}}\n// after\n{\"kv\": {\"field\": \"message\", \"field_split\": \" \", \"value_split\": \"=\", \"ignore_missing\": true}}","handlingStrategy":"validation","validationCode":"String path = document.renderTemplate(field);\nif (document.getFieldValue(path, String.class, true) == null) {\n    if (!ignoreMissing) {\n        // skip or set ignore_missing\n    }\n}","typeGuard":"static boolean kvFieldNotNull(IngestDocument doc, String path) {\n    return doc.getFieldValue(path, String.class, true) != null;\n}","tryCatchPattern":"try {\n    kvProcessor.execute(doc);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"is null, cannot extract\")) {\n        // route or set ignore_missing\n    } else throw e;\n}","preventionTips":["Set ignore_missing=true to cover null values.","Ensure upstream produces non-null string content for the kv field.","Drop documents with null source fields via a conditional before kv."],"tags":["ingest","kv","null-field","configuration"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:17:08.281Z"}