lionsoul2014/ip2region · critical

failed to load xdb content: %s

Error message

failed to load xdb content: %s

What it means

With cache_policy "content", the module loads the entire xdb into memory via xdb_load_content_from_file. NULL means the whole-file read or its memory allocation failed, so no content-cached searcher can be created.

Source

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

            }
            return NGX_CONF_ERROR;
        }

        err = xdb_new_with_vector_index(xdb_version, &ip2region_searcher->searcher, db_path, ip2region_searcher->v_index);
        xdb_free_header((void *)header);
        if (err != 0) {
            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                               "failed to create vector index cached searcher: %s", db_path);
            xdb_free_vector_index((void *)ip2region_searcher->v_index);
            if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
                free(db_path);
            }
            return NGX_CONF_ERROR;
        }
    } else if (strcmp(cache_policy, "content") == 0) {
        ip2region_searcher->c_buffer = xdb_load_content_from_file(db_path);
        if (ip2region_searcher->c_buffer == NULL) {
            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                               "failed to load xdb content: %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;
        }

        err = xdb_new_with_buffer(xdb_version, &ip2region_searcher->searcher, ip2region_searcher->c_buffer);
        xdb_free_header((void *)header);
        if (err != 0) {
            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                               "failed to create content cached searcher: %s", db_path);
            xdb_free_content((void *)ip2region_searcher->c_buffer);
            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

1. Check available memory (`free -m` / container limits) — the full xdb must fit in RAM; raise the limit or pick policy "file" or "vectorIndex".
2. Re-download and verify the xdb file size/checksum to rule out truncation.
3. Verify the nginx worker user can read the file.
4. If RAM is tight, switch ip2region_cache_policy to "vectorIndex" or "file".

Example fix

ip2region_cache_policy content;
# after (low memory environment)
ip2region_cache_policy vectorIndex;

#!/bin/bash
f=/data/ip2region.xdb
size=$(stat -c%s "$f")
avail=$(free -m | awk 'NR==2{print $7}')
[ $((size/1024/1024)) -lt $avail ] && echo "OK: xdb ($((size/1024/1024))MB) fits in ${avail}MB free" || echo "WARN: content policy needs $((size/1024/1024))MB RAM"
sha256sum -c ip2region.xdb.sha256 || echo "xdb corrupt/truncated"

When it happens

Trigger: xdb_load_content_from_file returns NULL: the file is unreadable (permissions), shorter than the content length declared in its header (truncated), or malloc of the full xdb size failed.

Common situations: Large xdb (hundreds of MB) under a low cgroup/container memory limit; truncated download; unreadable path for the worker user; file replaced mid-load.

Related errors

• failed to load vector index from: %s
• failed to create content cached searcher: %s
• failed to create searcher: %s
• incomplete read (${rBytes} read, ${header.HeaderInfoLength}
• failed to read embedded file `%s`: %w

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