lionsoul2014/ip2region · error · XdbException

invalid xdb structure version `${header.version}`

Error message

invalid xdb structure version `${header.version}`

What it means

Java Version.fromHeader rejects the xdb header: the structure version field is neither 2.0 (IPv4-only legacy) nor 3.0 (IPv6-capable), so the file is not a recognized xdb database — typically a corrupt, truncated, or foreign file.

Source

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

        if (n.equals("V4") || n.equals("IPV4")) {
            return IPv4;
        } else if (n.equals("V6") || n.equals("IPV6")) {
            return IPv6;
        } else {
            throw new Exception("invalid version name `"+name+"`");
        }
    }

    // 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. Regenerate or re-download a valid xdb produced by the current maker
2. Verify the file was not truncated in transfer (check size and header bytes)
3. Pass the correct file path instead of pointing at an unrelated binary

When it happens

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