apache/cassandra · error · RuntimeException

Could not reference sstables

Error message

Could not reference sstables

What it means

During validation (anti-entropy repair read phase), the CassandraValidationIterator selects sstables and tries to take references via Refs.tryRef; a null return means some sstables were compacted away or otherwise released between selection and referencing, so the iterator cannot safely read them. It logs an error for the parent repair session and throws this RuntimeException, aborting the validation for that session.

Source

Thrown at src/java/org/apache/cassandra/db/repair/CassandraValidationIterator.java:149

            // were marked as repairing, we would miss any ranges that were compacted away and this would cause us to overstream
            predicate = (s) -> !prs.isIncremental || !s.isRepaired();
        }

        try (ColumnFamilyStore.RefViewFragment sstableCandidates = cfs.selectAndReference(View.selectFunction(SSTableSet.CANONICAL)))
        {
            for (SSTableReader sstable : sstableCandidates.sstables)
            {
                if (new Bounds<>(sstable.getFirst().getToken(), sstable.getLast().getToken()).intersects(ranges) && predicate.apply(sstable))
                {
                    sstablesToValidate.add(sstable);
                }
            }

            sstables = Refs.tryRef(sstablesToValidate);
            if (sstables == null)
            {
                logger.error("Could not reference sstables for {}", parentId);
                throw new RuntimeException("Could not reference sstables");
            }
        }

        return sstables;
    }

    private final ColumnFamilyStore cfs;
    private final Refs<SSTableReader> sstables;
    private final String snapshotName;
    private final boolean isGlobalSnapshotValidation;

    private final boolean isSnapshotValidation;
    private final AbstractCompactionStrategy.ScannerList scanners;
    private final ValidationCompactionController controller;

    private final CompactionIterator ci;

    private final long estimatedBytes;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Retry the repair once compaction pressure subsides; transient races typically succeed on retry
2. Reduce concurrent compaction during repair (throttle compaction throughput with nodetool compactionthroughput)
3. Check node.log around the error for which sstable/parent session raced and whether compaction or cleanup removed it
4. Ensure the repair uses consistent versions and no storage bugs; if reproducible on idle nodes, file with logs for investigation

try { runRepair(); } catch (RuntimeException e) { if (e.getMessage().equals("Could not reference sstables")) { waitForCompactionQuiet(); retryRepair(); } else throw e; }

When it happens

Trigger: Heavy compaction activity concurrently removing candidate sstables while a validator is starting; races between lifecycle tracking and compaction leaving the sstable refcount unable to be acquired.

Common situations: Very active write workload with constant compaction during repair; many parallel repairs/compactions; long GC pauses delaying reference acquisition.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Unable to cancel in-progress compactions for {keyspace}.{tab
• You can't mix repaired and unrepaired data in a compaction
• Prepare phase failed because it encountered legacy sstables
• invalid global counter shard detected; ({}, {}, {}) and ({},
• invalid remote counter shard detected; ({}, {}, {}) and ({},

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