{"record":{"id":"cd8e3ef40cbd8f4a","repo":"lionsoul2014/ip2region","slug":"xdb-file-exceeds-the-maximum-supported-bytes-ma-cd8e3e","errorCode":null,"errorMessage":"xdb file exceeds the maximum supported bytes: ${maxFilePtr}","messagePattern":"xdb file exceeds the maximum supported bytes: (.+?)","errorType":"exception","errorClass":"XdbException","httpStatus":null,"severity":"error","filePath":"binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java","lineNumber":384,"sourceCode":"    //\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();\n    }\n\n    public static void verifyFromFile(String xdbPath) throws IOException, XdbException {\n        verifyFromFile(new File(xdbPath));\n    }\n\n}","sourceCodeStart":366,"sourceCodeEnd":402,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java#L366-L402","documentation":"For structure 2.0 the runtime pointer is 4 bytes, capping addressable file size at 2^32-1 bytes (or the header-declared runtimePtrBytes for 3.0). verify() rejects xdb files larger than this maximum because index pointers could not address the whole file, throwing XdbException.","triggerScenarios":"Calling Searcher.verify on an xdb whose size exceeds (1L << (runtimePtrBytes*8)) - 1 — practically, a >4GB xdb under STRUCTURE_20.","commonSituations":"Generating an enormous merged IP database with an old 2.0 maker; concatenating xdb files; mistakenly verifying an unrelated huge data file.","solutions":["Regenerate the xdb with STRUCTURE_30 (which supports larger runtime pointer bytes) via a 3.0-capable maker","Split the dataset into multiple xdb files each under the size limit","Confirm the file is actually the intended xdb and not a mistakenly large file"],"exampleFix":"// before\nmaker with STRUCTURE_20 producing 5GB xdb -> verify fails\n// after\nuse structure 3.0 maker (STRUCTURE_30) so runtimePtrBytes=8 covers large files","handlingStrategy":"validation","validationCode":"RandomAccessFile raf = new RandomAccessFile(xdbFile, \"r\");\nHeader h = Searcher.loadHeader(raf);\nint ptrBytes = (h.version == 2) ? 4 : h.runtimePtrBytes;\nlong maxFilePtr = (1L << (ptrBytes * 8)) - 1;\nif (new File(xdbFile).length() > maxFilePtr) throw new IllegalStateException(\"xdb too large for structure \" + h.version);","typeGuard":null,"tryCatchPattern":"try {\n    Searcher.verify(xdbFile);\n} catch (XdbException e) {\n    log.error(\"xdb exceeds pointer capacity; regenerate with structure 3.0\", e);\n}","preventionTips":["Use STRUCTURE_30 makers for very large datasets","Keep generated xdb sizes documented and checked in CI","Split oversized datasets into multiple xdb files"],"tags":["java","file-format","size-limit"],"backgroundTag":"xdb-size-limit-exceeded","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}