{"record":{"id":"638ebdd5b121c90c","repo":"elastic/elasticsearch","slug":"field-is-null-cannot-parse-user-agent","errorCode":null,"errorMessage":"field [{}] is null, cannot parse user-agent.","messagePattern":"field \\[(.+?)\\] is null, cannot parse user-agent\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/UserAgentProcessor.java","lineNumber":80,"sourceCode":"        this.ignoreMissing = ignoreMissing;\n    }\n\n    boolean isExtractDeviceType() {\n        return extractDeviceType;\n    }\n\n    boolean isIgnoreMissing() {\n        return ignoreMissing;\n    }\n\n    @Override\n    public IngestDocument execute(IngestDocument ingestDocument) {\n        String userAgent = ingestDocument.getFieldValue(field, String.class, ignoreMissing);\n\n        if (userAgent == null && ignoreMissing) {\n            return ingestDocument;\n        } else if (userAgent == null) {\n            throw new IllegalArgumentException(\"field [\" + field + \"] is null, cannot parse user-agent.\");\n        }\n\n        Details details = parser.parseUserAgentInfo(userAgent, extractDeviceType);\n\n        Map<String, Object> uaDetails = new HashMap<>();\n\n        for (Property property : this.properties) {\n            switch (property) {\n                case ORIGINAL:\n                    uaDetails.put(\"original\", userAgent);\n                    break;\n                case NAME:\n                    if (details.name() != null) {\n                        uaDetails.put(\"name\", details.name());\n                    } else {\n                        uaDetails.put(\"name\", \"Other\");\n                    }\n                    break;","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/UserAgentProcessor.java#L62-L98","documentation":"Thrown by UserAgentProcessor.execute when the configured source field resolves to null and ignore_missing is false. The processor cannot parse a user-agent string from null.","triggerScenarios":"Running the user_agent processor on a document where the source field (e.g., a header field) is absent or null, with ignore_missing omitted or set to false.","commonSituations":"Log ingestion where some events lack a user-agent header. HTTP request fields that are optional. Fields named inconsistently between sources.","solutions":["Set ignore_missing: true to tolerate absent user-agent fields.","Use an 'if' condition to skip the processor when the field is null.","Pre-populate the field with an empty string using a set processor if downstream processing needs it."],"exampleFix":"// before\n{\n  \"user_agent\": { \"field\": \"headers.user_agent\", \"target_field\": \"ua\" }\n}\n// after\n{\n  \"user_agent\": { \"field\": \"headers.user_agent\", \"target_field\": \"ua\", \"ignore_missing\": true }\n}","handlingStrategy":"validation","validationCode":"// Set ignore_missing: true on user_agent, or pre-check\nObject val = document.getFieldValue(\"headers.user_agent\", Object.class, true);\nif (val == null) {\n    // skip user_agent parsing; or configure ignore_missing: true\n}","typeGuard":"boolean hasUserAgentString(IngestDocument doc, String field) {\n    Object v = doc.getFieldValue(field, Object.class, true);\n    return v instanceof String;\n}","tryCatchPattern":"try {\n    // run user_agent processor\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"is null, cannot parse user-agent\")) {\n        // enable ignore_missing: true or add a guard\n    } else { throw e; }\n}","preventionTips":["Set ignore_missing: true for optional user-agent fields.","Add an 'if' condition to skip the processor when the field is null.","Validate header field names match the document structure."],"tags":["elasticsearch","ingest-pipeline","user-agent","validation","null-handling"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}