elastic/elasticsearch · error · IllegalArgumentException

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

Error message

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

What it means

Thrown by DatabaseProperty.parseProperty when the supplied string is not a valid DatabaseProperty enum name, or is a valid enum but not in the validProperties set for the current database. The message lists the allowed values in natural order. This validation runs once at processor construction time, so the sorting overhead is intentional for stable, readable errors.

Source

Thrown at libs/ip-location-api/src/main/java/org/elasticsearch/iplocation/api/DatabaseProperty.java:130

     * @param validProperties the valid properties against which to validate the parsed property value
     * @param value the string representation to parse
     * @return a parsed, validated DatabaseProperty
     * @throws IllegalArgumentException if the value does not parse as a DatabaseProperty or if the parsed value is not
     * in the passed-in validProperties set
     */
    public static DatabaseProperty parseProperty(final Set<DatabaseProperty> validProperties, final String value) {
        try {
            DatabaseProperty property = valueOf(value.toUpperCase(Locale.ROOT));
            if (validProperties.contains(property) == false) {
                throw new IllegalArgumentException("invalid");
            }
            return property;
        } catch (IllegalArgumentException e) {
            // put the properties in natural order before throwing so that we have reliable error messages -- this is a little
            // bit inefficient, but we only do this validation at processor construction time so the cost is practically immaterial
            DatabaseProperty[] properties = validProperties.toArray(new DatabaseProperty[0]);
            Arrays.sort(properties);
            throw new IllegalArgumentException("illegal property value [" + value + "]. valid values are " + Arrays.toString(properties));
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Read the 'valid values are [...]' list in the error message and use one of those exact values.
2. Cross-check the requested property against DatabaseProperty enum constants and confirm the database edition actually populates that field (build the validProperties set via DatabaseProperty.buildValidSet(info.getFields().keySet())).
3. If the property is legitimately needed, switch to a database edition/license tier that includes it.
4. Fix typos: field strings are case-insensitive but must match an enum name (e.g. COUNTRY_NAME), not an arbitrary label.

Example fix

// before
DatabaseProperty p = DatabaseProperty.parseProperty(validProps, "county_name");

// after
DatabaseProperty p = DatabaseProperty.parseProperty(validProps, "country_name");

// Validate before calling parseProperty
Set<DatabaseProperty> valid = DatabaseProperty.buildValidSet(info.getFields().keySet());
String candidate = "country_name"; // user-supplied
boolean ok = false;
for (DatabaseProperty dp : valid) {
    if (dp.name().equalsIgnoreCase(candidate)) { ok = true; break; }
}
if (!ok) {
    throw new IllegalArgumentException("Not a supported property for this database: " + candidate);
}
DatabaseProperty p = DatabaseProperty.parseProperty(valid, candidate);

// Returns true only if `value` maps to a DatabaseProperty in the valid set
static boolean isValidProperty(Set<DatabaseProperty> valid, String value) {
    if (value == null) return false;
    try {
        DatabaseProperty dp = DatabaseProperty.valueOf(value.toUpperCase(Locale.ROOT));
        return valid.contains(dp);
    } catch (IllegalArgumentException e) {
        return false;
    }
}

try {
    DatabaseProperty p = DatabaseProperty.parseProperty(validProperties, value);
} catch (IllegalArgumentException e) {
    // e.getMessage() already lists valid values; surface to config/UI
    throw newConfigurationException("ip-location property", value, e.getMessage());
}

When it happens

Trigger: Calling DatabaseProperty.parseProperty(validProperties, value) where `value` is either not parseable by valueOf (typo / unknown name) or parses but is excluded from validProperties (e.g. a field the loaded MaxMind database edition does not provide). The uppercased value is matched against the enum constants like COUNTRY_NAME, ASN, TOR_EXIT_NODE, etc.

Common situations: Configuring the ip-location ingest processor with a property name that the active database does not expose. Typos such as 'county_name' instead of 'country_name'. Using enterprise-only properties (e.g. ASN, anonymous_vpn) against a free City database. Mismatch between the field name string from IpDataLookupInfo and the enum.

Related errors

• Can't create extra config file from {} for {} as it does not
• extra jar file {} doesn't appear to be a JAR
• Not a valid module {} for {}
• extra config file destination can't be relative, was {} for
• Unknown keys in user definition {} for {}

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