lionsoul2014/ip2region · critical

failed to load vector index from: %s

Error message

failed to load vector index from: %s

What it means

With cache_policy "vectorIndex", the module first loads the vector index portion of the xdb into memory via xdb_load_vector_index_from_file. NULL means that read/allocation failed, so a vector-index-cached searcher cannot be built.

Source

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

        }
        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);
            }
            return NGX_CONF_ERROR;
        }
    } else if (strcmp(cache_policy, "vectorIndex") == 0) {
        ip2region_searcher->v_index = xdb_load_vector_index_from_file(db_path);
        if (ip2region_searcher->v_index == NULL) {
            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                               "failed to load vector index from: %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_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;

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Re-download/re-export a complete xdb and verify its size against the official release.
2. Confirm the nginx user can read the file and the disk is not full (`df -h`).
3. If memory-constrained, switch cache policy to "file" which avoids loading the vector index.
4. Ensure the file is not being overwritten while nginx starts (stage-and-rename deployments).

Example fix

ip2region_cache_policy vectorIndex;
# after (if memory constrained)
ip2region_cache_policy file;

#!/bin/bash
# full-file sanity: a truncated xdb cannot yield a vector index
f=/data/ip2region.xdb
[ $(stat -c%s "$f") -eq $(curl -sIL https://official-url/ip2region.xdb | awk '/content-length/{print $2}' | tr -d '\r') ] || echo "size mismatch: xdb is truncated"
free -m | awk 'NR==2{if ($7 < 512) print "WARN: low available memory for vector index"}'

When it happens

Trigger: xdb_load_vector_index_from_file returns NULL: the file disappeared or became unreadable between the header check and this call, the file is truncated (vector index region missing), or memory allocation for the index failed.

Common situations: Truncated/incomplete xdb download (header OK but index region cut off); disk full or malloc failure under memory limits; the file being replaced atomically while nginx is reloading config.

Related errors

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

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