apache/cassandra · critical · RuntimeException

Error initializing OnDiskOrdinalsMap at segment

Error message

Error initializing OnDiskOrdinalsMap at segment 

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnDiskOrdinalsMap.java:65

        this.fh = fh;
        try (var reader = fh.createReader())
        {
            reader.seek(segmentOffset);
            int deletedCount = reader.readInt();
            for (int i = 0; i < deletedCount; i++)
            {
                deletedOrdinals.add(reader.readInt());
            }

            this.ordToRowOffset = reader.getFilePointer();
            this.size = reader.readInt();
            reader.seek(segmentEnd - 8);
            this.rowOrdinalOffset = reader.readLong();
            assert rowOrdinalOffset < segmentEnd : "rowOrdinalOffset " + rowOrdinalOffset + " is not less than segmentEnd " + segmentEnd;
        }
        catch (Exception e)
        {
            throw new RuntimeException("Error initializing OnDiskOrdinalsMap at segment " + segmentOffset, e);
        }
    }

    public RowIdsView getRowIdsView()
    {
        return new RowIdsView();
    }

    public Bits ignoringDeleted(Bits acceptBits)
    {
        return BitsUtil.bitsIgnoringDeleted(acceptBits, deletedOrdinals);
    }

    public class RowIdsView implements AutoCloseable
    {
        final RandomAccessReader reader = fh.createReader();

        public int[] getSegmentRowIdsMatching(int vectorOrdinal) throws IOException

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. REBUILD the vector secondary index (or scrub the SSTable) to regenerate the segment files
2. Verify index component files are from the same segment generation; restore a consistent set from backup
3. Inspect the chained cause 'e' in the stack trace to identify the exact read/seek failure
4. Check the storage medium for errors (dmesg/fsck) if corruption recurs

Example fix

// caller-side resilience
try
{
    OnDiskOrdinalsMap map = new OnDiskOrdinalsMap(...);
}
catch (RuntimeException e)
{
    logger.error("Falling back to index rebuild for segment at " + segmentOffset, e);
    rebuildIndex();
}

if (!indexFile.exists() || indexFile.length() < segmentOffset + 8)
    throw new CorruptIndexException("ordinal map file too small for segment at " + segmentOffset, "vector");

boolean isReadableSegment(FileHandle fh, long segmentOffset) {
    try { return fh.length() >= segmentOffset + 8; } catch (Exception e) { return false; }
}

try {
    OnDiskOrdinalsMap map = new OnDiskOrdinalsMap(...);
} catch (RuntimeException e) {
    logger.error("Vector ordinal map init failed: {}", e.getMessage(), e);
    scheduleIndexRebuild();
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• 'null' deserialized value for %s with %s
• CQL type %s cannot have vector options
• Maximum node connections cannot be set without enabling %s
• Maximum number of connections %s is not a valid integer for
• Maximum number of connections for index %s cannot be <= 0 or

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/11c89035fe8f3051. Report an issue: GitHub.