elastic/elasticsearch · error · IllegalArgumentException

illegal property value [{}]. valid values are {}

Error message

illegal property value [{}]. valid values are {}

What it means

Thrown by Property.parseProperty when the property string cannot be matched to one of the enum values NAME, OS, DEVICE, ORIGINAL, VERSION (case-insensitively). This validates the 'properties' list in the user_agent processor config.

Source

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

                extractDeviceType,
                ignoreMissing
            );
        }
    }

    enum Property {

        NAME,
        OS,
        DEVICE,
        ORIGINAL,
        VERSION;

        public static Property parseProperty(String propertyName) {
            try {
                return valueOf(propertyName.toUpperCase(Locale.ROOT));
            } catch (IllegalArgumentException e) {
                throw new IllegalArgumentException(
                    "illegal property value ["
                        + propertyName
                        + "]. valid values are "
                        + Arrays.toString(EnumSet.allOf(Property.class).toArray())
                );
            }
        }
    }

    @UpdateForV10(owner = UpdateForV10.Owner.DISTRIBUTED)
    // This can be removed in V10. It's not possible to create an instance with the ecs property in V9, and all instances created by V8 or
    // earlier will have been fixed when upgraded to V9.
    static boolean maybeUpgradeConfig(Map<String, Object> config) {
        // Instances created using ES 8.x (or earlier) may have the 'ecs' config entry.
        // This was ignored in 8.x and is unsupported in 9.0.
        // In 9.x, we should remove it from any existing processors on startup.
        return config.remove("ecs") != null;
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Use only the allowed property names: name, os, device, original, version.
2. Remove or correct any unrecognized entry in the properties array.
3. Consult the processor documentation for the full valid property list.

Example fix

// before
{
  "user_agent": { "field": "ua", "properties": ["name", "browser"] }
}
// after
{
  "user_agent": { "field": "ua", "properties": ["name", "os", "device", "original", "version"] }
}

// Validate properties list against the allowed set before config
Set<String> allowed = Set.of("NAME", "OS", "DEVICE", "ORIGINAL", "VERSION");
for (String p : properties) {
    if (!allowed.contains(p.toUpperCase(Locale.ROOT))) {
        throw new IllegalArgumentException("invalid property: " + p);
    }
}

boolean isValidProperty(String name) {
    return Set.of("name", "os", "device", "original", "version").contains(name.toLowerCase(Locale.ROOT));
}

try {
    Property.parseProperty(propertyName);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("illegal property value")) {
        // remove or correct the invalid property name
    } else { throw e; }
}

When it happens

Trigger: Configuring the user_agent processor with a 'properties' array containing a value not in the allowed set, e.g., 'browser', 'engine', 'device_type', or any typo.

Common situations: Typos in property names. Using outdated or vendor-specific property names. Copying config from another user-agent parser library with different property names. Case is handled (uppercased), but unrecognized names still fail.

Related errors

• field [{}] is null, cannot parse user-agent.
• Resource count must be between 1 and 4
• failure store document has unexpected structure, missing req
• failure store document has unexpected structure, missing req
• unable to set domain information for document

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