lionsoul2014/ip2region · critical

failed to create content cached searcher: %s

Error message

failed to create content cached searcher: %s

What it means

nginx module init-time failure: with the content cache policy, xdb_load_content_from_file or the subsequent content-cached searcher creation failed, so the whole xdb could not be held in memory; the configuration is rejected with NGX_CONF_ERROR.

Source

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

            }
            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;
        }
    } else {
        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                           "invalid cache policy, options: file/vectorIndex/content");
        xdb_free_header((void *)header);
        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
            free(db_path);
        }
        return NGX_CONF_ERROR;
    }

    if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Free up memory or raise container/cgroup limits — creating the searcher needs additional allocations on top of the loaded content.
2. Re-download a verified, complete xdb of the version your module expects.
3. If memory cannot be spared, use cache policy "vectorIndex" or "file".
4. Retry nginx start once after confirming no transient memory pressure.

Example fix

ip2region_cache_policy content;
# after (memory constrained)
ip2region_cache_policy file;

#!/bin/bash
# extra headroom check: searcher creation allocates beyond the loaded content
f=/data/ip2region.xdb
need=$(( $(stat -c%s "$f") / 1024 / 1024 + 128 ))
avail=$(free -m | awk 'NR==2{print $7}')
[ $avail -gt $need ] && echo OK || echo "WARN: need ~${need}MB free, have ${avail}MB"

When it happens

Trigger: xdb_new_with_buffer returns != 0: internal searcher allocation failed (out of memory), or the buffer/header is inconsistent with the expected xdb version (file changed or malformed between load and bind).

Common situations: Very large xdb + low available RAM (second allocation failure on top of the content load); corrupted or mismatched data file passing the earlier checks; race with a file deployment not applicable here since content is in memory but header validation may mismatch.

Related errors

• failed to load xdb content: %s
• failed to determine xdb version from header: %s
• %s expects %s xdb file, but got %s: %s
• failed to create searcher: %s
• failed to load vector index from: %s

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