lionsoul2014/ip2region · error · XdbException

ip verison not match: xdb file ${xdbFile.getAbsolutePath()}

Error message

ip verison not match: xdb file ${xdbFile.getAbsolutePath()} (${xVersion.name}), as ${ipVersion.name} expected

What it means

When building a Config (which wires searchers to a data file), the Java binding compares the IP version requested (IPv4 or IPv6) with the ipVersion recorded in the xdb header. A mismatch — loading an IPv4 database through an IPv6-configured searcher or vice versa — throws XdbException naming the file, its version, and the expected version.

Source

Thrown at binding/java/src/main/java/org/lionsoul/ip2region/service/Config.java:63

    // config builder
    public static ConfigBuilder custom() {
        return new ConfigBuilder();
    }

    protected Config(int cachePolicy, Version ipVersion, File xdbFile, 
        Header header, byte[] vIndex, LongByteArray cBuffer, int searchers, boolean fairLock) throws IOException, XdbException {
        this.cachePolicy = cachePolicy;
        this.ipVersion = ipVersion;

        this.xdbFile = xdbFile;
        this.header  = header;
        this.vIndex  = vIndex;
        this.cBuffer = cBuffer;

        final Version xVersion = Version.fromHeader(header);
        // verify the ip version (ipVersion and the version of the xdb file should be the same)
        if (header.ipVersion != ipVersion.id) {
            throw new XdbException("ip verison not match: xdb file " 
                + xdbFile.getAbsolutePath() + " (" + xVersion.name + "), as " + ipVersion.name + " expected");
        }

        this.searchers = searchers;
        this.fairLock = fairLock;
    }

    @Override public String toString() {
        final StringBuffer sb = new StringBuffer();
        sb.append('{');
        sb.append("cache_policy:").append(cachePolicy).append(',');
        sb.append("version:").append(ipVersion.toString()).append(',');
        sb.append("xdb_path:").append(xdbFile == null ? "null" : xdbFile.getAbsolutePath()).append(',');
        sb.append("header:").append(header.toString()).append(',');
        if (vIndex == null) {
            sb.append("v_index: null, ");
        } else {
            sb.append("v_index: {bytes: ").append(vIndex.length).append("},");

View on GitHub (pinned to c1a1fc7d59)

Solutions

Point the config's xdbFile at the database matching the requested IP version (city.ipv4.xdb for IPv4, city.ipv6.xdb for IPv6), or change ipVersion to match the file.
Check Version.fromHeader(header) output to see which family the file actually is before wiring it in.
In shared config, parameterize both the db path and ipVersion together so they can't diverge.
Regenerate the xdb with the maker for the desired IP version if the wrong one was built.

Example fix

// before
new Config(xdbFile, header, Version.IPv6, ...) // file is city.ipv4.xdb
// after
new Config(new File("data/city.ipv6.xdb"), header, Version.IPv6, ...)

Defensive patterns

Strategy: validation

Validate before calling

Version fileVersion = Version.fromHeader(header);
if (fileVersion.id != ipVersion.id)
  throw new IllegalArgumentException("xdb " + xdbFile + " is " + fileVersion.name + " but IPv4/IPv6 " + ipVersion.name + " expected");

Try / catch

try {
  config = new Config(xdbFile, header, ipVersion, vIndex, cBuffer, searchers, fairLock);
} catch (XdbException e) {
  if (e.getMessage().contains("ip verison not match")) {
    // swap in the db file matching ipVersion, or flip ipVersion to match the file
    throw new IllegalStateException("configure matching db path + ipVersion", e);
  }
  throw e;
}

Prevention

Keep db path and ipVersion in one config object so they can't drift apart.
Name files explicitly (city.ipv4.xdb / city.ipv6.xdb) and assert the suffix matches the configured version at startup.
Smoke-test one lookup per searcher at boot to surface mismatches immediately.

When it happens

Trigger: Constructing Config with ipVersion = IPv6 while pointing xdbFile at an IPv4 city xdb (or the reverse); copying config code between the ipv4 and ipv6 sample apps without swapping the db path; using an un-versioned/legacy xdb whose header version does not equal the requested id.

Common situations: Deployment where the config's db path was changed (e.g. to an ip2region v4 file) but the code still requests IPv6; teams shipping both city.ipv4.xdb and city.ipv6.xdb and mixing them in shared configuration.

Related errors

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