{"record":{"id":"11c89035fe8f3051","repo":"apache/cassandra","slug":"error-initializing-ondiskordinalsmap-at-segment","errorCode":null,"errorMessage":"Error initializing OnDiskOrdinalsMap at segment ","messagePattern":"Error initializing OnDiskOrdinalsMap at segment ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnDiskOrdinalsMap.java","lineNumber":65,"sourceCode":"        this.fh = fh;\n        try (var reader = fh.createReader())\n        {\n            reader.seek(segmentOffset);\n            int deletedCount = reader.readInt();\n            for (int i = 0; i < deletedCount; i++)\n            {\n                deletedOrdinals.add(reader.readInt());\n            }\n\n            this.ordToRowOffset = reader.getFilePointer();\n            this.size = reader.readInt();\n            reader.seek(segmentEnd - 8);\n            this.rowOrdinalOffset = reader.readLong();\n            assert rowOrdinalOffset < segmentEnd : \"rowOrdinalOffset \" + rowOrdinalOffset + \" is not less than segmentEnd \" + segmentEnd;\n        }\n        catch (Exception e)\n        {\n            throw new RuntimeException(\"Error initializing OnDiskOrdinalsMap at segment \" + segmentOffset, e);\n        }\n    }\n\n    public RowIdsView getRowIdsView()\n    {\n        return new RowIdsView();\n    }\n\n    public Bits ignoringDeleted(Bits acceptBits)\n    {\n        return BitsUtil.bitsIgnoringDeleted(acceptBits, deletedOrdinals);\n    }\n\n    public class RowIdsView implements AutoCloseable\n    {\n        final RandomAccessReader reader = fh.createReader();\n\n        public int[] getSegmentRowIdsMatching(int vectorOrdinal) throws IOException","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnDiskOrdinalsMap.java#L47-L83","documentation":"RuntimeException wrapper thrown by the OnDiskOrdinalsMap constructor when any exception occurs while initializing the memory-mapped ordinal map for a vector segment: seeking to the segment end, reading the rowOrdinalOffset footer, or validating it against segmentEnd. It chains the underlying exception and includes the segment offset for diagnosis.","triggerScenarios":"Opening a vector segment whose ordinal-map file is truncated or corrupt, footer readLong fails, an assertion fails (rowOrdinalOffset >= segmentEnd), or the segment offset points into invalid data.","commonSituations":"Corrupted or partially written vector index files after a crash, files copied inconsistently (data from one generation, metadata from another), or storage errors during mmap/read.","solutions":["REBUILD the vector secondary index (or scrub the SSTable) to regenerate the segment files","Verify index component files are from the same segment generation; restore a consistent set from backup","Inspect the chained cause 'e' in the stack trace to identify the exact read/seek failure","Check the storage medium for errors (dmesg/fsck) if corruption recurs"],"exampleFix":"// caller-side resilience\ntry\n{\n    OnDiskOrdinalsMap map = new OnDiskOrdinalsMap(...);\n}\ncatch (RuntimeException e)\n{\n    logger.error(\"Falling back to index rebuild for segment at \" + segmentOffset, e);\n    rebuildIndex();\n}","handlingStrategy":"try-catch","validationCode":"if (!indexFile.exists() || indexFile.length() < segmentOffset + 8)\n    throw new CorruptIndexException(\"ordinal map file too small for segment at \" + segmentOffset, \"vector\");","typeGuard":"boolean isReadableSegment(FileHandle fh, long segmentOffset) {\n    try { return fh.length() >= segmentOffset + 8; } catch (Exception e) { return false; }\n}","tryCatchPattern":"try {\n    OnDiskOrdinalsMap map = new OnDiskOrdinalsMap(...);\n} catch (RuntimeException e) {\n    logger.error(\"Vector ordinal map init failed: {}\", e.getMessage(), e);\n    scheduleIndexRebuild();\n}","preventionTips":["Treat index components as atomic; restore them together from the same backup","Rebuild vector indexes after any crash or disk error","Inspect chained causes to detect recurring storage problems"],"tags":["cassandra","sai","vector-index","corruption"],"backgroundTag":"file-read-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}