elastic/elasticsearch · error · IllegalArgumentException

invalid database configuration id [{}]: id doesn't match req

Error message

invalid database configuration id [{}]: id doesn't match required rules (alphanumerics, dashes, and underscores, only)

What it means

Thrown by DatabaseConfiguration.validateId when the id does not match ID_PATTERN (\\p{Alnum}[_\\-\\p{Alnum}]{0,126}). The id must START with an alphanumeric character and may contain only alphanumerics, dashes, and underscores thereafter. Leading dashes and underscores are explicitly reserved by Elasticsearch for future internal use and are rejected even though they technically match a loose reading.

Source

Thrown at modules/ip-location/src/main/java/org/elasticsearch/ingest/geoip/direct/DatabaseConfiguration.java:182

     * An id is intended to be alphanumerics, dashes, and underscores (only), but we're reserving leading dashes and underscores for
     * ourselves in the future, that is, they're not for the ones that users can PUT.
     */
    static void validateId(String id) throws IllegalArgumentException {
        if (Strings.isNullOrEmpty(id)) {
            throw new IllegalArgumentException("invalid database configuration id [" + id + "]: must not be null or empty");
        }
        MetadataCreateIndexService.validateIndexOrAliasName(
            id,
            (id1, description) -> new IllegalArgumentException("invalid database configuration id [" + id1 + "]: " + description)
        );
        int byteCount = id.getBytes(StandardCharsets.UTF_8).length;
        if (byteCount > 127) {
            throw new IllegalArgumentException(
                "invalid database configuration id [" + id + "]: id is too long, (" + byteCount + " > " + 127 + ")"
            );
        }
        if (ID_PATTERN.matcher(id).matches() == false) {
            throw new IllegalArgumentException(
                "invalid database configuration id ["
                    + id
                    + "]: id doesn't match required rules (alphanumerics, dashes, and underscores, only)"
            );
        }
    }

    public ActionRequestValidationException validate() {
        ActionRequestValidationException err = new ActionRequestValidationException();

        // how do we cross the id validation divide here? or do we? it seems unfortunate to not invoke it at all.

        // name validation
        if (Strings.hasText(name) == false) {
            err.addValidationError("invalid name [" + name + "]: cannot be empty");
        }

        // provider-specific name validation

View on GitHub (pinned to db6a809a66)

Solutions

Rename the id to start with a letter/digit and use only [A-Za-z0-9_-], e.g. 'city-db' or 'geoip_city_01'.
Remove leading dashes and underscores: '_city' -> 'city', '-internal' -> 'internal'.
Strip or replace disallowed characters (dots, spaces, accents) before submitting the id.

Example fix

// before
PUT _ingest/geoip/database/my.geoip.city

// after
PUT _ingest/geoip/database/my-geoip-city

Defensive patterns

Strategy: validation

Validate before calling

// ID_PATTERN = \\p{Alnum}[_\\-\\p{Alnum}]{0,126}
private static final Pattern ID_OK = Pattern.compile("\\p{Alnum}[_\\-\\p{Alnum}]{0,126}");
String id = requestConfig.getId();
if (!ID_OK.matcher(id).matches()) {
    throw new IllegalArgumentException("id must be alphanumerics, dashes, underscores; must start with alphanumeric");
}

Prevention

Start ids with a letter or digit; never a dash or underscore.
Avoid dots, spaces, slashes, and accented characters in ids.
Sanitize generated ids by replacing disallowed chars with '-' before submitting.

When it happens

Trigger: PUT _ingest/geoip/database/<id> where <id> contains dots, spaces, slashes, or other special characters, or begins with a dash/underscore. Examples that fail: 'my.db', 'my db', '-city', '_internal', 'city!', 'café'.

Common situations: Using index-style names with dots; copying an id from another system that permits leading underscores; URL-decoding artifacts introducing spaces; i18n names with accented characters.

Related errors

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