lionsoul2014/ip2region · error · XdbException

invalid ip version number `${header.ipVersion}`

Error message

invalid ip version number `${header.ipVersion}`

What it means

Java Version.fromHeader: the structure version is 3.0 but the header's ipVersion field matches neither the IPv4 nor the IPv6 version number, so the address family of the database cannot be determined; the header is corrupt or from an unsupported xdb variant.

Source

Thrown at binding/java/src/main/java/org/lionsoul/ip2region/xdb/Version.java:76

    // parse the version from header
    public static final Version fromHeader(Header header) throws XdbException {
        // Old 2.0 structure with IPv4 supports ONLY.
        if (header.version == Searcher.STRUCTURE_20) {
            return IPv4;
        }

        // structure 3.0 after IPv6 supporting
        if (header.version != Searcher.STRUCTURE_30) {
            throw new XdbException("invalid xdb structure version `"+header.version+"`");
        }

        if (header.ipVersion == IPv4VersionNo) {
            return IPv4;
        } else if (header.ipVersion == IPv6VersionNo) {
            return IPv6;
        } else {
            throw new XdbException("invalid ip version number `" + header.ipVersion + "`");
        }
    }

    @Override public String toString() {
        return String.format("{Id:%d, Name:%s, Bytes:%d, IndexSize: %d}", id, name, bytes, segmentIndexSize);
    }
}

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Use an xdb file generated by a maker that writes a valid ipVersion header field
2. Re-download/regenerate the database to eliminate corruption
3. If you control the maker, ensure the header encodes 1 (IPv4) or 2 (IPv6) as expected

When it happens

Trigger: Thrown at binding/java/src/main/java/org/lionsoul/ip2region/xdb/Version.java:76 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/859e1243a63348d1. Report an issue: GitHub.