What causes "Failed to update per-SSTable components for SSTable {}" in apache/cassandra?

Read the attached exception `t` in the log to identify the exact failure (missing file vs format mismatch).

Failed to update per-SSTable components for SSTable

Error message

Failed to update per-SSTable components for SSTable {}

What it means

SSTableContextManager.update obtains per-SSTable SAI components (index descriptors, per-column SSTable indexes) via a computeIfAbsent that creates an SSTableContext. If context creation/loading throws, the exception is logged at WARN (with the SAI index descriptor prefix) and the SSTable is added to the `invalid` set and its cached context removed, so queries avoid that SSTable instead of failing.

Solutions

Read the attached exception `t` in the log to identify the exact failure (missing file vs format mismatch).
Run `nodetool scrub <keyspace> <table>` or rebuild the affected SSTable's index via nodetool rebuild_index.
If format mismatch after upgrade, run a full index rebuild so SAI components are rewritten in the current format.
Replace the damaged SSTable by running repair to re-replicate its data.

Defensive patterns

Strategy: validation

Try / catch

try { sstableContextManager.update(sstables); } catch (Throwable t) { logger.warn("SSTable context failed; excluding SSTable from SAI queries", t); }

Prevention

Avoid manual copying of SSTables without their SAI .sc components.
Perform full SAI index rebuilds after major version upgrades.
Monitor disk health; SAI component corruption disables index segments.
Use nodetool scrub on suspect SSTables before reopening them.

When it happens

Trigger: Opening SAI index components for an SSTable whose segment files are corrupted, were written by an incompatible SAI version, or are missing — raised from SSTableContext.create inside update().

Common situations: Upgrading/downgrading between Cassandra versions with changed SAI on-disk format; disk corruption; partial flush/interrupted compaction leaving incomplete SAI components; manually copied SSTables without their .sc component files.

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

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/SSTableContextManager.java:94

                continue;
            }

            try
            {
                // Only validate on restart or newly refreshed SSTable. Newly built files are unlikely to be corrupted.
                if (!sstableContexts.containsKey(sstable) && !indexDescriptor.validatePerSSTableComponents(validation, true, false))
                {
                    invalid.add(sstable);
                    removeInvalidSSTableContext(sstable);
                    continue;
                }
                // ConcurrentHashMap#computeIfAbsent guarantees atomicity, so {@link SSTableContext#create(SSTableReader)}}
                // is called at most once per key.
                contexts.add(sstableContexts.computeIfAbsent(sstable, SSTableContext::create));
            }
            catch (Throwable t)
            {
                logger.warn(indexDescriptor.logMessage("Failed to update per-SSTable components for SSTable {}"), sstable.descriptor, t);
                invalid.add(sstable);
                removeInvalidSSTableContext(sstable);
            }
        }

        return Pair.create(contexts, invalid);
    }

    public void release(Collection<SSTableReader> toRelease)
    {
        toRelease.stream().map(sstableContexts::remove).filter(Objects::nonNull).forEach(SSTableContext::close);
    }

    /**
     * @return total number of per-sstable open files for live sstables
     */
    int openFiles()
    {

View on GitHub (pinned to 88fd0f6a0e)