lionsoul2014/ip2region · warning

no IPv4 searcher available for IPv4 address

Error message

no IPv4 searcher available for IPv4 address

What it means

At request time, the ip2region nginx variable is evaluated for an AF_INET (IPv4) client connection, but the module's IPv4 searcher was never initialized (v4_searcher == NULL). The module logs a warning and the variable yields an empty value instead of a region.

Source

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

    if (ip2region_conf->v4_searcher == NULL && ip2region_conf->v6_searcher == NULL) {
        v->not_found = 1;
        return NGX_OK;
    }

    // 初始化 region buffer
    err = xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));
    if (err != 0) {
        v->not_found = 1;
        return NGX_OK;
    }

    switch (r->connection->sockaddr->sa_family) {
        case AF_INET:
            sin = (struct sockaddr_in *) r->connection->sockaddr;

            // 检查是否有IPv4 searcher
            if (ip2region_conf->v4_searcher == NULL) {
                ngx_log_error(NGX_LOG_WARN, r->connection->log, 0,
                              "no IPv4 searcher available for IPv4 address");
                break;
            }

            searcher_ptr = &ip2region_conf->v4_searcher->searcher;

            // 正确转换IP地址字节序，按ip2region期望的格式
            ip = ntohl(sin->sin_addr.s_addr); // 将网络字节序转换为主机字节序
            // 按照xdb_parse_v4_ip中的格式重新组织字节
            {
                bytes_ip_t ip_bytes[4];
                ip_bytes[0] = (ip >> 24) & 0xFF;
                ip_bytes[1] = (ip >> 16) & 0xFF;
                ip_bytes[2] = (ip >> 8) & 0xFF;
                ip_bytes[3] = ip & 0xFF;
                err = xdb_search(searcher_ptr, ip_bytes, 4, &region);
            }
            if (err == 0) {

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Add the IPv4 database directive: ip2region_db_file /path/to/ip2region_v4.xdb alongside the v6 one.
2. Check nginx startup logs for earlier ip2region init errors and fix them so the v4 searcher initializes.
3. If IPv4 lookups are intentionally unsupported, remove the variable from IPv4-serving log formats or handle empty values.
4. Verify with `nginx -T` that both v4 and v6 directives are present in the relevant server/http block.

Example fix

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

nginx -T 2>/dev/null | grep -E 'ip2region_db_file( |_v6)' # assert BOTH v4 and v6 directives exist before serving dual-stack traffic

When it happens

Trigger: A request arrives over IPv4 while only ip2region_db_file_v6 (IPv6 searcher) was configured, or the IPv4 init failed earlier / the directive was omitted, and something references the ip2region variable in log_format, headers, etc.

Common situations: Dual-stack server where operators configured only the v6 xdb but log_format includes $ip2region for all requests; local/loopback IPv4 health checks hitting a v6-only setup; silent init failure at startup that was missed.

Related errors

• ip2region search failed for IPv4 address
• invalid bytes ip with length not 4 or 16
• ip verison not match: xdb file ${xdbFile.getAbsolutePath()}
• failed to allocate memory for db_path
• failed to load xdb header from: %s

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