apache/cassandra · warning

Missing component

Error message

Missing component: %s

What it means

During scrub of a big-format SSTable, the scrubber checks for the PRIMARY_INDEX (-Index.db) component. If it does not exist on disk it emits this warning and proceeds to scrub without the index, meaning partition sizes/positions cannot be cross-validated and corrupt partitions cannot be skipped over reliably.

Solutions

1. Restore the missing -Index.db file from a backup or re-stream the sstable from a replica
2. Run scrub accepting no index-based skipping if the data file is trusted
3. Run `nodetool repair` so healthy replicas replace the degraded sstable
4. If the data file is also suspect, rebuild the data from client-side sources or snapshots

Example fix

// before: sstable missing -Index.db
boolean hasIndexFile = sstable.descriptor.fileFor(Components.PRIMARY_INDEX).exists();
// after: pre-check components before scrubbing
if (!sstable.descriptor.fileFor(Components.PRIMARY_INDEX).exists())
    logger.warn("{} missing primary index; restore from snapshot/replica before scrub", sstable);

File idx = sstable.descriptor.fileFor(Components.PRIMARY_INDEX);
if (!idx.exists())
    throw new IllegalStateException("SSTable is missing " + idx + "; restore before scrub");

When it happens

Trigger: Running `nodetool scrub` (BigTableScrubber constructor) on an SSTable whose descriptor.fileFor(Components.PRIMARY_INDEX) does not exist — the -Index.db file was deleted, lost, or the table was moved/restored incompletely.

Common situations: Incomplete backup restores, manual sstable copying that omitted sidecar components, disk cleanup scripts deleting 'extra' files, or a crash during compaction leaving partial sstables.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Data file partition position
• Data file partition position
• Error reading partition
• Error reading partition
• Failed to advance to the next index position. Index is…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/sstable/format/big/BigTableScrubber.java:68

    private ByteBuffer nextIndexKey;
    private long currentPartitionPositionFromIndex;
    private long nextPartitionPositionFromIndex;

    public BigTableScrubber(ColumnFamilyStore cfs,
                            LifecycleTransaction transaction,
                            OutputHandler outputHandler,
                            Options options)
    {
        super(cfs, transaction, outputHandler, options);

        this.rowIndexEntrySerializer = new RowIndexEntry.Serializer(sstable.descriptor.version, sstable.header, cfs.getMetrics());

        boolean hasIndexFile = sstable.descriptor.fileFor(Components.PRIMARY_INDEX).exists();
        this.isIndex = cfs.isIndex();
        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 component: %s", sstable.descriptor.fileFor(Components.PRIMARY_INDEX));
        }

        this.indexFile = hasIndexFile
                         ? RandomAccessReader.open(sstable.descriptor.fileFor(Components.PRIMARY_INDEX))
                         : null;

        this.currentPartitionPositionFromIndex = 0;
        this.nextPartitionPositionFromIndex = 0;
    }

    @Override
    protected UnfilteredRowIterator withValidation(UnfilteredRowIterator iter, String filename)
    {
        return options.checkData && !isIndex ? UnfilteredRowIterators.withValidation(iter, filename) : iter;
    }

    @Override
    protected void scrubInternal(SSTableRewriter writer) throws IOException

View on GitHub (pinned to 88fd0f6a0e)