What causes "failed to load xdb header from: %s" in lionsoul2014/ip2region?

Verify db_path exists and is readable by the nginx master user (ls -l / sudo -u nginx head -c256 file)

lionsoul2014/ip2region · critical

failed to load xdb header from: %s

Error message

failed to load xdb header from: %s

What it means

After resolving db_path, the nginx module loads the xdb header via xdb_load_header_from_file to detect the IP version. A NULL return means the file could not be read or its header is invalid, so the module logs 'failed to load xdb header from: <path>' (plus the freed relative path handling) and rejects the config.

Source

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

        strcat(db_path, db_name);
    }

    ip2region_searcher = ngx_palloc(cf->pool, sizeof(ip2region_searcher_t));

    if(ip2region_searcher == NULL) {
        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
            free(db_path);
        }
        return NGX_CONF_ERROR;
    }

    ip2region_searcher->v_index = NULL;
    ip2region_searcher->c_buffer = NULL;

    // 检查XDB文件的版本信息以确定IP类型
    xdb_header_t *header = xdb_load_header_from_file(db_path);
    if (header == NULL) {
        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                           "failed to load xdb header from: %s", db_path);
        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
            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;
    }

View on GitHub (pinned to c1a1fc7d59)

Solutions

Verify db_path exists and is readable by the nginx master user (ls -l / sudo -u nginx head -c256 file)
Correct the path in nginx.conf or deploy the xdb file to the configured location
Re-download/rebuild the xdb file if its header is corrupt (check size/checksum)
Check SELinux/AppArmor denial logs and grant read access to the file

Example fix

# before
ip2region_db /etc/nginx/region.xdb;   # file missing
# after
# deploy first: cp region.xdb /etc/nginx/region.xdb && chown nginx /etc/nginx/region.xdb
ip2region_db /etc/nginx/region.xdb;

Defensive patterns

Strategy: validation

Validate before calling

# shell check before starting nginx
test -r /path/to/region.xdb && [ $(stat -c%s /path/to/region.xdb) -ge 256 ] || echo "xdb missing or truncated"

Try / catch

/* module returns NGX_CONF_ERROR; verify config at deploy time */
nginx -t || exit 1   # surfaces 'failed to load xdb header from: <path>' early

Prevention

Deploy and permission-check the xdb file before nginx reloads
Use absolute, stable paths managed by config management
Verify file size/checksum after every database update
Ensure nginx user can read the file (and SELinux/AppArmor allows it)
Run nginx -t in CI/deploy pipelines to fail before restart

When it happens

Trigger: db_path pointing to a missing, unreadable, empty, or corrupt/non-xdb file; permission denied for the nginx worker/master user; xdb_load_header_from_file failing on a truncated header.

Common situations: Wrong path in nginx.conf (file never deployed), xdb file deleted by a cleanup job, SELinux/AppArmor blocking read, file uploaded incompletely, ownership not readable by nginx user.

Related errors

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