{"record":{"id":"52b7a38721fff948","repo":"lionsoul2014/ip2region","slug":"incomplete-read-read-bytes-should-be-len","errorCode":null,"errorMessage":"incomplete read: read bytes should be ${len}","messagePattern":"incomplete read: read bytes should be (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java","lineNumber":244,"sourceCode":"    }\n\n    public static Header loadHeaderFromFile(String xdbPath) throws IOException {\n        return loadHeaderFromFile(new File(xdbPath));\n    }\n\n    public static Header loadHeaderFromBuffer(LongByteArray cBuffer) throws IOException {\n        return new Header(cBuffer.slice(0, HeaderInfoLength));\n    }\n\n    // --- read xdb vector index\n\n    public static byte[] loadVectorIndex(RandomAccessFile handle) throws IOException {\n        handle.seek(HeaderInfoLength);\n        int len = VectorIndexRows * VectorIndexCols * VectorIndexSize;\n        final byte[] buff = new byte[len];\n        int rLen = handle.read(buff);\n        if (rLen != len) {\n            throw new IOException(\"incomplete read: read bytes should be \" + len);\n        }\n\n        return buff;\n    }\n\n    public static byte[] loadVectorIndexFromFile(File xdbFile) throws IOException {\n        final RandomAccessFile handle = new RandomAccessFile(xdbFile, \"r\");\n        final byte[] vIndex = loadVectorIndex(handle);\n        handle.close();\n        return vIndex;\n    }\n\n    public static byte[] loadVectorIndexFromFile(String xdbPath) throws IOException {\n        return loadVectorIndexFromFile(new File(xdbPath));\n    }\n\n    public static byte[] loadVectorIndexFromBuffer(LongByteArray cBuffer) throws IOException {\n        final int len = VectorIndexRows * VectorIndexCols * VectorIndexSize;","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/java/src/main/java/org/lionsoul/ip2region/xdb/Searcher.java#L226-L262","documentation":"loadVectorIndex reads VectorIndexRows*VectorIndexCols*VectorIndexSize bytes starting at HeaderInfoLength and requires a single full read. A short read means the xdb file is smaller than a valid structure or IO failed, so an IOException is thrown.","triggerScenarios":"Calling Searcher.loadVectorIndex(handle)/loadVectorIndexFromFile on a truncated xdb file (less than 256+vector-index bytes) or on a partially copied/downloaded file.","commonSituations":"Incomplete uploads of the xdb to servers/containers; using an empty placeholder file; corrupted cache of the xdb in CI.","solutions":["Re-download or re-copy a complete xdb file and check its size matches the original","Call Searcher.verify(raf) before building the searcher to detect bad files early","Use atomic file publication (write temp file, then rename) so readers never see partial files"],"exampleFix":"// before\nbyte[] vIndex = Searcher.loadVectorIndexFromFile(new File(\"partial.xdb\"));\n// after\nRandomAccessFile raf = new RandomAccessFile(\"full.xdb\", \"r\");\nSearcher.verify(raf); // throws XdbException on bad files\nbyte[] vIndex = Searcher.loadVectorIndex(raf);","handlingStrategy":"validation","validationCode":"File f = new File(xdbFile);\nif (f.length() < 256 + 256*256*4) throw new IllegalStateException(\"xdb too small for vector index\");\nSearcher.verify(new RandomAccessFile(f, \"r\"));","typeGuard":null,"tryCatchPattern":"try {\n    byte[] vIndex = Searcher.loadVectorIndexFromFile(f);\n} catch (IOException e) {\n    log.error(\"failed to load vector index, falling back to file mode\", e);\n    vIndex = null;\n}","preventionTips":["Check file size against the official release before loading","Download with checksum verification and atomic rename","Run Searcher.verify once at startup for every xdb asset"],"tags":["java","io","corrupt-file"],"backgroundTag":"incomplete-read","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}