lionsoul2014/ip2region · warning

ip2region search failed for IPv4 address

Error message

ip2region search failed for IPv4 address

What it means

The IPv4 searcher exists and xdb_search_by_string was called with the client IP, but it returned a non-zero error, so no region string could be produced. The variable is left empty and a warning is logged per failing request. This indicates the lookup itself failed against the loaded database (not a config abort).

Source

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

            // 正确转换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) {
                v->data = (unsigned char *)region.value;
                v->len = strlen(region.value);
                xdb_region_buffer_free(&region);
                return NGX_OK;
            } else {
                ngx_log_error(NGX_LOG_WARN, r->connection->log, 0,
                              "ip2region search failed for IPv4 address");
            }
            break;

#if (NGX_HAVE_INET6)

        case AF_INET6:
            sin6 = (struct sockaddr_in6 *) r->connection->sockaddr;
            p = sin6->sin6_addr.s6_addr;

            if (IN6_IS_ADDR_V4MAPPED(&sin6->sin6_addr)) {
                // 处理IPv4映射的IPv6地址
                if (ip2region_conf->v4_searcher != NULL) {
                    searcher_ptr = &ip2region_conf->v4_searcher->searcher;
                    addr = p[12] << 24;
                    addr += p[13] << 16;
                    addr += p[14] << 8;
                    addr += p[15];

View on GitHub (pinned to c1a1fc7d59)

Solutions

  1. Verify the loaded xdb is complete and matches the module's expected version; re-download it.
  2. Test the same IP against the xdb with the official xdb CLI/binding (`search` tool) to see if the DB itself errors.
  3. Check which client IPs trigger it — malformed or proxy-injected addresses may need real_ip handling ($realip_remote_addr).
  4. If the searcher state is suspect, restart nginx to rebuild searchers from the current file.
  5. Ensure the module and xdb data are from compatible ip2region versions.

Example fix

# before (possibly proxy-supplied bogus address)
log_format main '$ip2region ...';
# after (search on the original client address)
log_format main '$realip_remote_addr=$ip2region ...';
real_ip_header X-Forwarded-For;
Defensive patterns

Strategy: try-catch

Validate before calling

# verify the DB can resolve a known IP using the official CLI before trusting it in nginx
xdb search --db=/data/ip2region.xdb --ip=1.2.3.4 || echo "xdb itself fails on known IP -> reload or replace the db"

Try / catch

# nginx.conf: give the lookup variable a fallback via map
map $ip2region $ip2region_or_unknown {
    ""      "unknown";   # covers search failures and empty results
    default $ip2region;
}
log_format main '$remote_addr region=$ip2region_or_unknown';

Prevention

When it happens

Trigger: xdb_search_by_string returns err != 0 for the given IPv4 string: malformed/unexpected IP input reaching the searcher, an invalid or mismatched searcher/db state (e.g. db reloaded or corrupt), or internal search failure (bad index offsets).

Common situations: Requests from odd addresses (e.g. 0.0.0.0 or unix-socket-derived values coerced into IPv4 form); truncated or corrupted xdb loaded at startup; using an xdb version not matching the module build so offsets resolve incorrectly.

Related errors

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