{"record":{"id":"dea2e0fa566dccf4","repo":"lionsoul2014/ip2region","slug":"xdb-file-ip-version-mismatch-expected-ipversion","errorCode":null,"errorMessage":"xdb file IP version mismatch: expected ${ipVersion.name}, got ${detectedVersion.name}","messagePattern":"xdb file IP version mismatch: expected (.+?), got (.+?)","errorType":"validation","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"binding/cangjie/src/service/config.cj","lineNumber":37,"sourceCode":"    public let searchers: Int64\n\n    public init(cachePolicy: Int64, ipVersion: Version, xdbPath: String, searchers: Int64) {\n        if (searchers <= 0) {\n            throw Exception(\"searchers must be > 0\")\n        }\n\n        this.cachePolicy = cachePolicy\n        this.ipVersion = ipVersion\n        this.xdbPath = xdbPath\n        this.searchers = searchers\n\n        let content = File.readFrom(Path(xdbPath))\n        this.header = newHeaderFromBytes(content)\n\n        // Verify IP version matches\n        let detectedVersion = versionFromHeader(this.header)\n        if (detectedVersion.id != ipVersion.id) {\n            throw Exception(\"xdb file IP version mismatch: expected ${ipVersion.name}, got ${detectedVersion.name}\")\n        }\n\n        if (cachePolicy == VectorIndex) {\n            this.vIndex = loadVectorIndex(content)\n            this.cBuffer = Array<Byte>(0, repeat: 0)\n        } else if (cachePolicy == ContentBuff) {\n            this.vIndex = Array<Byte>(0, repeat: 0)\n            this.cBuffer = content\n        } else {\n            this.vIndex = Array<Byte>(0, repeat: 0)\n            this.cBuffer = Array<Byte>(0, repeat: 0)\n        }\n    }\n\n    public init(cachePolicy: Int64, ipVersion: Version, xdbPath: String) {\n        this(cachePolicy, ipVersion, xdbPath, 20)\n    }\n}","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/cangjie/src/service/config.cj#L19-L55","documentation":"During Config initialization the xdb file's header is parsed and its detected IP version is compared with the ipVersion the caller requested. If they differ, the exception names both versions, because a searcher built for one address family cannot correctly query a database of the other.","triggerScenarios":"Constructing Config with ipVersion = V6 while pointing xdbPath at an IPv4-only .xdb (or vice versa); reusing a config/path constant after switching database files.","commonSituations":"Deploying the v6 database but leaving the v4 path in the config, upgrading from an IPv4 xdb to an IPv6 one without updating ipVersion, mixing files from different downloads.","solutions":["Make ipVersion match the actual file (check the message's 'got' side to see what the file is)","Download/load the correct .xdb variant for the configured version (v4 file for V4, v6 file for V6)","Detect the version from the header first (versionFromHeader) and pass that into Config instead of hardcoding","Separate config keys for v4 and v6 database paths if both are needed"],"exampleFix":"// before\nlet cfg = Config(policy, Version.V6, \"ip.v4.xdb\", 4) // mismatch\n// after\nlet header = newHeaderFromBytes(File.readFrom(Path(xdbPath)))\nlet ver = versionFromHeader(header)\nlet cfg = Config(policy, ver, xdbPath, 4)","handlingStrategy":"validation","validationCode":"// Cangjie: detect version from file before constructing Config\nlet content = File.readFrom(Path(xdbPath))\nlet ver = versionFromHeader(newHeaderFromBytes(content))\nif (ver.id != desiredVersion.id) { log.error(\"xdb is ${ver.name}, config wants ${desiredVersion.name}\") }","typeGuard":"func versionMatches(path: String, want: Version): Bool {\n    let h = newHeaderFromBytes(File.readFrom(Path(path)))\n    return versionFromHeader(h).id == want.id\n}","tryCatchPattern":"try {\n    let cfg = Config(policy, ipVersion, xdbPath, poolSize)\n} catch (e: Exception) {\n    if (e.message.contains(\"version mismatch\")) { /* reload correct xdb or fix ipVersion */ }\n    throw e\n}","preventionTips":["Keep separate config keys for v4/v6 database paths","Detect the version from the header instead of hardcoding ipVersion","Name xdb files with their version (ip.v4.xdb / ip.v6.xdb) and check the name","Verify after every database deploy/upgrade"],"tags":["cangjie","config","ip-version-mismatch","xdb"],"backgroundTag":"ip-version-mismatch","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}