apache/cassandra · warning

{} failed for index component {} on SSTable {}

Error message

{} failed for index component {} on SSTable {}

What it means

V1OnDiskFormat.validateIndexComponent logs this warning when opening/checking a Storage-Attached Index (SAI) index component file on an SSTable throws an exception. Depending on whether the component was written with a checksum, either SAICodecUtils.validateChecksum or SAICodecUtils.validate failed, meaning the on-disk index component is corrupt, unreadable, or was written by an incompatible version. After logging, the exception is rethrown as an IOException, so callers (compaction, index build, query path) will see the failure propagate.

Source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/V1OnDiskFormat.java:338

    }

    private static void validateIndexComponent(IndexDescriptor indexDescriptor,
                                               IndexIdentifier indexContext,
                                               IndexComponent indexComponent,
                                               boolean checksum)
    {
        try (IndexInput input = indexContext == null
                                ? indexDescriptor.openPerSSTableInput(indexComponent)
                                : indexDescriptor.openPerIndexInput(indexComponent, indexContext))
        {
            if (checksum)
                SAICodecUtils.validateChecksum(input);
            else
                SAICodecUtils.validate(input);
        }
        catch (Exception e)
        {
            logger.warn(indexDescriptor.logMessage("{} failed for index component {} on SSTable {}"),
                        checksum ? "Checksum validation" : "Validation", indexComponent, indexDescriptor.sstableDescriptor);
            rethrowIOException(e);
        }
    }

    private static void rethrowIOException(Exception e)
    {
        if (e instanceof IOException)
            throw new UncheckedIOException((IOException) e);
        if (e.getCause() instanceof IOException)
            throw new UncheckedIOException((IOException) e.getCause());
        throw Throwables.unchecked(e);
    }

    @Override
    public Set<IndexComponent> perSSTableIndexComponents(boolean hasClustering)
    {
        return hasClustering ? WIDE_PER_SSTABLE_COMPONENTS : SKINNY_PER_SSTABLE_COMPONENTS;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Run nodetool scrub or repair on the affected SSTables to rebuild damaged index components, or run an offline full scrub with --no-sanity-checks if needed
2. Drop and rebuild the SAI index (DROP INDEX then CREATE INDEX) so all per-SSTable index components are regenerated from live data
3. Check dmesg/filesystem health (xfs_repair/fsck) on the node; move the node out of rotation and replace the damaged disk
4. Restore the SSTable set from a good snapshot or backup if the index components and data files are inconsistent

Example fix

// before: trusting SSTables copied from another node
Files.copy(srcIndexComponent, destIndexComponent);
// after: rebuild index components on the target node instead of copying them
nodetool repair -pr keyspace table; // then DROP/CREATE INDEX to regenerate SAI components

// before loading an SSTable's SAI index, verify components exist and are non-empty
for (String comp : expectedIndexComponents)
{
    File f = new File(sstableDir, baseName + comp);
    if (!f.exists() || f.length() == 0)
        throw new IOException("Index component missing or empty: " + f);
}

try { format.validateIndexComponents(descriptor, ...); }
catch (IOException e)
{
    logger.error("Index component validation failed for {} - marking index unusable and scheduling rebuild", descriptor, e);
    rebuildIndex();
}

When it happens

Trigger: Calling validatePerSSTableIndexComponents or validatePerColumnIndexComponents during SAI index load/repair when an index component file (e.g. .tok, .kdi, meta files) is truncated, bit-rotted on disk, or fails CRC/checksum verification in SAICodecUtils.

Common situations: Disk corruption or failing hardware on a node; an interrupted compaction or flush left a partial index component; the SSTable was copied/restored manually and files are inconsistent; a Cassandra version upgrade changed the index component format and validation logic rejects older files.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• Key from data file (%s) does not match key from index file (
• Trailing data encountered in segment index
• 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/5a2d385bf1f5a232. Report an issue: GitHub.