lionsoul2014/ip2region · critical

%s expects %s xdb file, but got %s: %s

Error message

%s expects %s xdb file, but got %s: %s

What it means

The xdb header was parsed successfully, but its version does not match the version expected by the directive used: ip2region_db_file expects the IPv4-format xdb and ip2region_db_file_v6 expects the IPv6-format xdb. The module compares xdb_version->id with expected_version->id and aborts configuration when they differ.

Source

Thrown at binding/nginx/src/ngx_http_ip2region_module.c:142

            free(db_path);
        }
        return NGX_CONF_ERROR;
    }

    xdb_version_t *xdb_version = xdb_version_from_header(header);
    if (xdb_version == NULL) {
        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                           "failed to determine xdb version from header: %s", db_path);
        xdb_free_header((void *)header);
        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
            free(db_path);
        }
        return NGX_CONF_ERROR;
    }

    // 验证XDB文件版本是否匹配
    if (xdb_version->id != expected_version->id) {
        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                           "%s expects %s xdb file, but got %s: %s",
                           directive_name, expected_version->name, xdb_version->name, db_path);
        xdb_free_header((void *)header);
        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
            free(db_path);
        }
        return NGX_CONF_ERROR;
    }

    if (strcmp(cache_policy, "file") == 0) {
        err = xdb_new_with_file_only(xdb_version, &ip2region_searcher->searcher, db_path);
        xdb_free_header((void *)header);
        if (err != 0) {
            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                               "failed to create searcher: %s", db_path);
            if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
                free(db_path);
            }

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Match the directive to the file: use ip2region_db_file for the IPv4 xdb and ip2region_db_file_v6 for the IPv6 xdb.
2. Swap the two file paths in nginx.conf if they are crossed.
3. Re-download the correct-region xdb (ip2region v4 or v6 data) matching your module build.
4. Check the logged expected vs got version names to confirm which file to replace.

Example fix

# before
ip2region_db_file /data/ip2region_v6.xdb;
# after
ip2region_db_file /data/ip2region_v4.xdb;
ip2region_db_file_v6 /data/ip2region_v6.xdb;

#!/bin/bash
# pair each directive with the right file: name files by region and assert
v4=/data/ip2region_v4.xdb; v6=/data/ip2region_v6.xdb
grep -E 'ip2region_db_file(\s|;)' nginx.conf | grep -q "$v4" || echo "WARN: ip2region_db_file should point to the v4 xdb"
grep -q "ip2region_db_file_v6.*$v6" nginx.conf || echo "WARN: ip2region_db_file_v6 should point to the v6 xdb"

When it happens

Trigger: Using `ip2region_db_file` with an IPv6-region xdb file, or `ip2region_db_file_v6` with an IPv4-region xdb file; also mixing data files from different ip2region generations (e.g. v2 xdb with a v3-expecting directive).

Common situations: Upgrading ip2region and keeping an old data file; copying the v4 xdb path into the v6 directive (or vice versa) in nginx.conf; having both ip2region_v4.xdb and ip2region_v6.xdb and wiring them swapped.

Related errors

• failed to determine xdb version from header: %s
• failed to create searcher: %s
• failed to create vector index cached searcher: %s
• failed to create content cached searcher: %s
• ip verison not match: xdb file ${xdbFile.getAbsolutePath()}

AI-assisted analysis of lionsoul2014/ip2region@c1a1fc7d59 (2026-09-02). Data as JSON: /api/errors/b72d82588721e79f. Report an issue: GitHub.