{"record":{"id":"53aa7cb5831e986e","repo":"lionsoul2014/ip2region","slug":"no-ipv4-searcher-available-for-ipv4-address","errorCode":null,"errorMessage":"no IPv4 searcher available for IPv4 address","messagePattern":"no IPv4 searcher available for IPv4 address","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"binding/nginx/src/ngx_http_ip2region_module.c","lineNumber":380,"sourceCode":"    if (ip2region_conf->v4_searcher == NULL && ip2region_conf->v6_searcher == NULL) {\n        v->not_found = 1;\n        return NGX_OK;\n    }\n\n    // 初始化 region buffer\n    err = xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));\n    if (err != 0) {\n        v->not_found = 1;\n        return NGX_OK;\n    }\n\n    switch (r->connection->sockaddr->sa_family) {\n        case AF_INET:\n            sin = (struct sockaddr_in *) r->connection->sockaddr;\n\n            // 检查是否有IPv4 searcher\n            if (ip2region_conf->v4_searcher == NULL) {\n                ngx_log_error(NGX_LOG_WARN, r->connection->log, 0,\n                              \"no IPv4 searcher available for IPv4 address\");\n                break;\n            }\n\n            searcher_ptr = &ip2region_conf->v4_searcher->searcher;\n\n            // 正确转换IP地址字节序，按ip2region期望的格式\n            ip = ntohl(sin->sin_addr.s_addr); // 将网络字节序转换为主机字节序\n            // 按照xdb_parse_v4_ip中的格式重新组织字节\n            {\n                bytes_ip_t ip_bytes[4];\n                ip_bytes[0] = (ip >> 24) & 0xFF;\n                ip_bytes[1] = (ip >> 16) & 0xFF;\n                ip_bytes[2] = (ip >> 8) & 0xFF;\n                ip_bytes[3] = ip & 0xFF;\n                err = xdb_search(searcher_ptr, ip_bytes, 4, &region);\n            }\n            if (err == 0) {","sourceCodeStart":362,"sourceCodeEnd":398,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/nginx/src/ngx_http_ip2region_module.c#L362-L398","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the IPv4 database directive: ip2region_db_file /path/to/ip2region_v4.xdb alongside the v6 one.","Check nginx startup logs for earlier ip2region init errors and fix them so the v4 searcher initializes.","If IPv4 lookups are intentionally unsupported, remove the variable from IPv4-serving log formats or handle empty values.","Verify with `nginx -T` that both v4 and v6 directives are present in the relevant server/http block."],"exampleFix":"# before\nip2region_db_file_v6 /data/ip2region_v6.xdb;\n# after\nip2region_db_file /data/ip2region_v4.xdb;\nip2region_db_file_v6 /data/ip2region_v6.xdb;","handlingStrategy":"fallback","validationCode":"nginx -T 2>/dev/null | grep -E 'ip2region_db_file( |_v6)' # assert BOTH v4 and v6 directives exist before serving dual-stack traffic","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always configure both ip2region_db_file and ip2region_db_file_v6 on dual-stack servers.","Watch for NGX_LOG_WARN 'no IPv4/IPv6 searcher' lines at startup and in runtime logs.","Make the log_format handle an empty ip2region variable gracefully (e.g. default via map).","Fix any conf-time ip2region init errors instead of letting nginx start half-initialized."],"tags":["nginx","runtime","ipv4","missing-config"],"backgroundTag":"searcher-not-initialized","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}