lionsoul2014/ip2region · error

ip2region search failed for IPv4-mapped IPv6 address

Error message

ip2region search failed for IPv4-mapped IPv6 address

What it means

nginx runtime warning: xdb_search returned non-zero for an IPv4-mapped IPv6 address (::ffff:a.b.c.d) after the module re-packed the low 32 bits into a v4 byte array — the v4 lookup itself failed (typically a corrupted index or a v4 searcher in a bad state); the variable is left unset and the request continues.

Source

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

                    addr += p[13] << 16;
                    addr += p[14] << 8;
                    addr += p[15];
                    // 按照xdb_parse_v4_ip中的格式重新组织字节
                    {
                        bytes_ip_t ip_bytes[4];
                        ip_bytes[0] = (addr >> 24) & 0xFF;
                        ip_bytes[1] = (addr >> 16) & 0xFF;
                        ip_bytes[2] = (addr >> 8) & 0xFF;
                        ip_bytes[3] = addr & 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-mapped IPv6 address");
                    }
                }
            } else {
                // 处理纯IPv6地址
                if (ip2region_conf->v6_searcher != NULL) {
                    searcher_ptr = &ip2region_conf->v6_searcher->searcher;
                    bytes_ip_t ip6_bytes[16];
                    if (p != NULL) {
                        memcpy(ip6_bytes, p, 16);
                        err = xdb_search(searcher_ptr, ip6_bytes, 16, &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,

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Check the v4 searcher and xdb file integrity (verify the db)
2. Ensure the v4 db covers the mapped address range or accept empty results
3. Monitor the warn log rate to detect a systematically broken searcher

When it happens

Trigger: Thrown at binding/nginx/src/ngx_http_ip2region_module.c:438 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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