apache/cassandra · error · IndexOutOfBoundsException

The requested position exceeds the index length

Error message

The requested position exceeds the index length

What it means

SSTableCursorKeyReader.seek() validates that the requested offset lies within the on-disk primary index. Seeking past indexLength() would read outside the index file, so an IndexOutOfBoundsException is thrown instead.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/SSTableCursorKeyReader.java:138

        }
        entry.load(indexFileReader);
        return true;
    }

    public boolean isExhausted()
    {
        return indexFileReader.isEOF();
    }

    public long indexPosition()
    {
        return indexFileReader.getFilePointer();
    }

    public void seek(long position) throws IOException
    {
        if (position > indexLength())
            throw new IndexOutOfBoundsException("The requested position exceeds the index length");
        indexFileReader.seek(position);
    }

    public long indexLength()
    {
        return indexFileReader.length();
    }

    public void reset() throws IOException
    {
        indexFileReader.seek(initialPosition);
    }

    @Override
    public String toString()
    {
        return String.format("BigTable-SSTableCursorKeyReader(%s), indexPosition=%d", indexFile.path(), indexFileReader.getFilePointer());
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Clear the key cache (nodetool invalidatekeycache or restart) to drop stale offsets.
2. Verify the sstable with sstableverify / nodetool verify; scrub or rebuild if the index is truncated.
3. Restore the -Index.db file from backup if truncated.
4. In custom code, clamp/validate the offset against indexLength() before calling seek.

Example fix

// before
reader.seek(position);
// after
if (position >= 0 && position <= reader.indexLength()) {
    reader.seek(position);
} else {
    // recompute offset from index summary before retrying
}

if (position < 0 || position > keyReader.indexLength())
    throw new IllegalArgumentException("offset " + position + " outside index length " + keyReader.indexLength());

try {
    keyReader.seek(position);
} catch (IndexOutOfBoundsException e) {
    // invalidate cached offset (key cache) and recompute from index summary
}

When it happens

Trigger: Calling seek(position) where position > indexFileReader.length() — typically an offset computed from a corrupted index summary or stale key-cache entry exceeding the actual index file size.

Common situations: Corrupt or truncated -Index.db files; stale key cache entries after an sstable was replaced/truncated; interrupted writes leaving a short index file; buggy offset computation.

Related errors

• The requested position exceeds the index length
• Key from data file (%s) does not match key from index file (
• Failed to update per-column components for SSTable {}
• Corrupt flags value for clustering prefix (isStatic flag set
• Corrupted sstable. Invalid flags found deserializing Deletio

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