{"record":{"id":"ce55d2d19a4f1f38","repo":"lionsoul2014/ip2region","slug":"invalid-structure-version-header-version-ce55d2","errorCode":null,"errorMessage":"invalid structure version `${header.version}`","messagePattern":"invalid structure version `(.+?)`","errorType":"exception","errorClass":"XdbException","httpStatus":null,"severity":"error","filePath":"binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java","lineNumber":377,"sourceCode":"    }\n\n    // --- verify util function\n\n    // Verify if the current Searcher could be used to search the specified xdb file.\n    // Why do we need this check ?\n    // The future features of the xdb impl may cause the current searcher not able to work properly.\n    //\n    // @Note: You Just need to check this ONCE when the service starts\n    // Or use another process (eg, A command) to check once Just to confirm the suitability.\n    public static void verify(Header header, long fileBytes) throws IOException, XdbException {\n        // get the runtime ptr bytes\n        int runtimePtrBytes = 0;\n        if (header.version == STRUCTURE_20) {\n            runtimePtrBytes = 4;\n        } else if (header.version == STRUCTURE_30) {\n            runtimePtrBytes = header.runtimePtrBytes;\n        } else {\n            throw new XdbException(\"invalid structure version `\" + header.version + \"`\");\n        }\n\n        // 1, confirm the xdb file size\n        // to ensure that the maximum file pointer does not overflow\n        final long maxFilePtr = (1L << (runtimePtrBytes * 8)) - 1;\n        if (fileBytes > maxFilePtr) {\n            throw new XdbException(\"xdb file exceeds the maximum supported bytes: \"+maxFilePtr+\"\");\n        }\n    }\n\n    public static void verify(RandomAccessFile handle) throws IOException, XdbException {\n        verify(loadHeader(handle), handle.length());\n    }\n\n    public static void verifyFromFile(File xdbFile) throws IOException, XdbException {\n        final RandomAccessFile handle = new RandomAccessFile(xdbFile, \"r\");\n        verify(handle);\n        handle.close();","sourceCodeStart":359,"sourceCodeEnd":395,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java#L359-L395","documentation":"verify() reads the xdb header and only supports structure versions STRUCTURE_20 (4-byte runtime pointers) and STRUCTURE_30 (variable runtimePtrBytes). A header with any other version number means the file was not produced by a compatible ip2region writer or is corrupted, so an XdbException is thrown.","triggerScenarios":"Running Searcher.verify / verify(handle) on an xdb generated by an incompatible/older tool, a random file passed as xdb, or a file whose header bytes are corrupted.","commonSituations":"Mixing xdb files from different projects/branches of ip2region; pointing the searcher at a placeholder or wrong-format IP database; bit rot in stored assets.","solutions":["Regenerate the xdb with a compatible maker that emits structure 2.0 or 3.0","Ensure you downloaded the official ip2region.xdb for this library version, not another IP DB format","Re-download the file if the header may be corrupted, then run verify again"],"exampleFix":"// before\nSearcher.verify(otherVendorIpDb); // unknown header version\n// after\nSearcher.verify(new File(\"ip2region.xdb\")); // official 2.0/3.0 structure","handlingStrategy":"validation","validationCode":"RandomAccessFile raf = new RandomAccessFile(xdbFile, \"r\");\ntry {\n    Searcher.verify(raf); // throws XdbException on bad version\n} finally { raf.close(); }","typeGuard":null,"tryCatchPattern":"try {\n    Searcher.verify(xdbFile);\n} catch (XdbException e) {\n    log.error(\"incompatible or corrupt xdb: {}\", e.getMessage());\n    throw new IllegalStateException(\"replace the xdb file\", e);\n}","preventionTips":["Only use xdb files from the matching ip2region release/maker","Run Searcher.verify at startup before building searchers","Don't repurpose other vendors' IP databases as xdb input"],"tags":["java","file-format","version-mismatch"],"backgroundTag":"invalid-xdb-structure-version","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}