apache/cassandra · critical · RuntimeException

Error seeking to index offset for ordinal

Error message

Error seeking to index offset for ordinal %d with ordToRowOffset %d

What it means

RuntimeException thrown when FileHandle/DataInput seek fails while positioning the reader at the index offset for a vector ordinal during getSegmentRowIdsMatching. The computed offset is ordToRowOffset + 4 + vectorOrdinal*8; a seek failure there indicates the ordinal map data is shorter or corrupt relative to the metadata offsets.

Solutions

1. REBUILD the vector index to regenerate a consistent ordinal map file
2. Validate that the queried ordinal is within the segment's vector count before lookup
3. Ensure component files come from the same segment generation; restore a matching set from backup
4. Check the chained cause to distinguish mmap/IO failures from offset computation bugs

Example fix

// guard before lookup
if (vectorOrdinal < 0 || vectorOrdinal >= vectorCount)
    throw new IllegalArgumentException("ordinal out of range: " + vectorOrdinal);
rowIds = ordinalsMap.getSegmentRowIdsMatching(vectorOrdinal);

if (vectorOrdinal < 0 || vectorOrdinal >= vectorCount)
    throw new IllegalArgumentException("ordinal out of range for segment: " + vectorOrdinal);

boolean ordinalInSegment(int ordinal, int vectorCount) {
    return ordinal >= 0 && ordinal < vectorCount;
}

try {
    rowIds = ordinalsMap.getSegmentRowIdsMatching(ordinal);
} catch (RuntimeException e) {
    logger.error("Ordinal lookup failed: {}", e.getMessage(), e);
    return emptyRowIds(); // or mark segment unhealthy
}

When it happens

Trigger: Querying a vector segment where ordToRowOffset or the ordinal points beyond the mapped region, the file is truncated, or the map was initialized against mismatched segment bounds.

Common situations: Truncated/corrupt vector index files, version mismatch between writer and reader layouts, ordinals requested that exceed the segment's vector count, or mismatched component files after manual file moves.

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

• Error seeking to rowIds offset for ordinal
• Construction beam width cannot be set without enabling
• Construction beam width for index
• Construction beam width
• CQL type cannot have vector options

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

Appendix: source

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

        return BitsUtil.bitsIgnoringDeleted(acceptBits, deletedOrdinals);
    }

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

        public int[] getSegmentRowIdsMatching(int vectorOrdinal) throws IOException
        {
            Preconditions.checkArgument(vectorOrdinal < size, "vectorOrdinal %s is out of bounds %s", vectorOrdinal, size);

            // read index entry
            try
            {
                reader.seek(ordToRowOffset + 4L + vectorOrdinal * 8L);
            }
            catch (Exception e)
            {
                throw new RuntimeException(String.format("Error seeking to index offset for ordinal %d with ordToRowOffset %d",
                                                         vectorOrdinal, ordToRowOffset), e);
            }
            long offset = reader.readLong();
            // seek to and read rowIds
            try
            {
                reader.seek(offset);
            }
            catch (Exception e)
            {
                throw new RuntimeException(String.format("Error seeking to rowIds offset for ordinal %d with ordToRowOffset %d",
                                                         vectorOrdinal, ordToRowOffset), e);
            }
            int postingsSize = reader.readInt();
            int[] rowIds = new int[postingsSize];
            for (int i = 0; i < rowIds.length; i++)
            {
                rowIds[i] = reader.readInt();

View on GitHub (pinned to 88fd0f6a0e)