What causes "invalid database configuration id [{}]: must not be null or empty" in elastic/elasticsearch?

Supply a non-empty id in the request path, e.g. PUT _ingest/geoip/database/my-city-db.

elastic/elasticsearch · error · IllegalArgumentException

invalid database configuration id [{}]: must not be null or

Error message

invalid database configuration id [{}]: must not be null or empty

What it means

Thrown by DatabaseConfiguration.validateId when the GeoIP database configuration id is null or empty. The id is the URL path segment of the PUT/DELETE _ingest/geoip/database configuration API and must be supplied as a non-blank string. This is the first guard in a chain that also checks index-name validity, byte length, and an alphanumeric/dash/underscore pattern.

Source

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

        out.writeNamedWriteable(provider);
    }

    @Override
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
        builder.startObject();
        builder.field("name", name);
        builder.field(provider.getWriteableName(), provider);
        builder.endObject();
        return builder;
    }

    /**
     * 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)"
            );
        }

View on GitHub (pinned to db6a809a66)

Solutions

Supply a non-empty id in the request path, e.g. PUT _ingest/geoip/database/my-city-db.
If generating the id programmatically, default it to a stable name and assert it is non-blank before issuing the request.
Check the client SDK call site that constructs the path for a null/empty variable substitution.

Example fix

// before
PUT _ingest/geoip/database/
{ "name": "City", "maxmind": { "account_id": "123" } }

// after
PUT _ingest/geoip/database/my-city-db
{ "name": "City", "maxmind": { "account_id": "123" } }

Defensive patterns

Strategy: validation

Validate before calling

// Validate the GeoIP database config id before issuing PUT/DELETE
String id = requestConfig.getId();
if (id == null || id.trim().isEmpty()) {
    throw new IllegalArgumentException("GeoIP database configuration id must not be null or empty");
}

Prevention

Always pass an explicit id segment in the _ingest/geoip/database/<id> URL path.
Assert the id is non-blank in client code before building the request URL.
Use the same id consistently for create/update to avoid empty-substitution bugs.

When it happens

Trigger: Calling PUT _ingest/geoip/database/<id> (or DELETE) where <id> is omitted, an empty string, or whitespace-only. The id is parsed from the REST path before the body is read, so a malformed URL like PUT _ingest/geoip/database/ with nothing after the last slash hits this.

Common situations: URL-templating bugs in client code that leave the id blank; copy/paste of an API example with a placeholder never replaced; automated scripts that build the path from an unset variable; retry logic that drops the id on a second attempt.

Related errors

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