apache/cassandra · warning

Detected corruption in the index file - cannot open index…

Error message

Detected corruption in the index file - cannot open index iterator

What it means

Opening the BTI partition-index iterator threw a RuntimeException, indicating the index file is corrupt or cannot be parsed. The scrubber warns and continues scrubbing without the index, degrading its ability to skip corrupt partitions.

Solutions

1. Replace the sstable from a healthy replica via repair/rebuild
2. Restore the -PartitionIndex.db from a snapshot
3. Run scrub accepting degraded (index-less) behavior, then repair
4. Check filesystem/disk health; run fsck/SMART checks on the data directory

Example fix

// before: corrupt BTI index degrades the scrub
catch (RuntimeException ex) { outputHandler.warn("Detected corruption in the index file - cannot open index iterator", ex); }
// after: detect corruption before scrub
nodetool verify keyspace table; // replaces sstable if index is corrupt
nodetool scrub keyspace table;

try {
    sstable.scrubPartitionsIterator(); // probe open
} catch (RuntimeException e) {
    logger.warn("BTI index corrupt; replace sstable before scrub", e);
}

try {
    iterator = sstable.scrubPartitionsIterator();
} catch (RuntimeException ex) {
    logger.warn("Index corrupt, scrubbing without index", ex);
    iterator = null;
}

When it happens

Trigger: BtiTableScrubber constructor: openIndexIterator() throws RuntimeException (e.g. from BTI index file parsing/validation) — corrupt -PartitionIndex.db, invalid metadata/footer, or a truncated file.

Common situations: Bit-rot or truncated index after unclean shutdown, sstable corrupted in transit during restore, incompatible index file version after a version downgrade.

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 reading index file
• Failed to dump trie to
• Index is unreadable, scrubbing will continue without index.
• An error occurred while scrubbing the partition with key
• Cannot create index on non-frozen UDT column

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/sstable/format/bti/BtiTableScrubber.java:72

        boolean hasIndexFile = sstable.getComponents().contains(Components.PARTITION_INDEX);
        this.isIndex = cfs.isIndex();
        this.partitionKeyType = cfs.metadata.get().partitionKeyType;
        if (!hasIndexFile)
        {
            // if there's any corruption in the -Data.db then partitions can't be skipped over. but it's worth a shot.
            outputHandler.warn("Missing index component");
        }

        try
        {
            this.indexIterator = hasIndexFile
                                 ? openIndexIterator()
                                 : null;
        }
        catch (RuntimeException ex)
        {
            outputHandler.warn("Detected corruption in the index file - cannot open index iterator", ex);
        }
    }

    private ScrubPartitionIterator openIndexIterator()
    {
        try
        {
            return sstable.scrubPartitionsIterator();
        }
        catch (Throwable t)
        {
            outputHandler.warn(t, "Index is unreadable, scrubbing will continue without index.");
        }
        return null;
    }

    @Override
    protected UnfilteredRowIterator withValidation(UnfilteredRowIterator iter, String filename)

View on GitHub (pinned to 88fd0f6a0e)