elastic/elasticsearch · error · IllegalArgumentException

field [{}] is null, cannot parse user-agent.

Error message

field [{}] is null, cannot parse user-agent.

What it means

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.

Source

Thrown at modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/UserAgentProcessor.java:80

        this.ignoreMissing = ignoreMissing;
    }

    boolean isExtractDeviceType() {
        return extractDeviceType;
    }

    boolean isIgnoreMissing() {
        return ignoreMissing;
    }

    @Override
    public IngestDocument execute(IngestDocument ingestDocument) {
        String userAgent = ingestDocument.getFieldValue(field, String.class, ignoreMissing);

        if (userAgent == null && ignoreMissing) {
            return ingestDocument;
        } else if (userAgent == null) {
            throw new IllegalArgumentException("field [" + field + "] is null, cannot parse user-agent.");
        }

        Details details = parser.parseUserAgentInfo(userAgent, extractDeviceType);

        Map<String, Object> uaDetails = new HashMap<>();

        for (Property property : this.properties) {
            switch (property) {
                case ORIGINAL:
                    uaDetails.put("original", userAgent);
                    break;
                case NAME:
                    if (details.name() != null) {
                        uaDetails.put("name", details.name());
                    } else {
                        uaDetails.put("name", "Other");
                    }
                    break;

View on GitHub (pinned to db6a809a66)

Solutions

1. Set ignore_missing: true to tolerate absent user-agent fields.
2. Use an 'if' condition to skip the processor when the field is null.
3. Pre-populate the field with an empty string using a set processor if downstream processing needs it.

Example fix

// before
{
  "user_agent": { "field": "headers.user_agent", "target_field": "ua" }
}
// after
{
  "user_agent": { "field": "headers.user_agent", "target_field": "ua", "ignore_missing": true }
}

// Set ignore_missing: true on user_agent, or pre-check
Object val = document.getFieldValue("headers.user_agent", Object.class, true);
if (val == null) {
    // skip user_agent parsing; or configure ignore_missing: true
}

boolean hasUserAgentString(IngestDocument doc, String field) {
    Object v = doc.getFieldValue(field, Object.class, true);
    return v instanceof String;
}

try {
    // run user_agent processor
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is null, cannot parse user-agent")) {
        // enable ignore_missing: true or add a guard
    } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: Log ingestion where some events lack a user-agent header. HTTP request fields that are optional. Fields named inconsistently between sources.

Related errors

• field [{}] is null, cannot sort.
• field [{}] is null, cannot split.
• illegal property value [{}]. valid values are {}
• field [{}] is null, cannot extract geoip information.
• failure store document has unexpected structure, missing req

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