apache/cassandra · error · IllegalStateException

Missing SAI index to import for SSTable %s on %s.%s

Error message

Missing SAI index to import for SSTable %s on %s.%s

What it means

SSTableImporter.importNewSSTables refuses to import an SSTable whose SAI (Storage-Attached Index) per-SSTable index build is not complete. Importing such an SSTable would attach a table with missing/incomplete index files, so it throws IllegalStateException naming the descriptor, keyspace, and table.

Source

Thrown at src/java/org/apache/cassandra/db/SSTableImporter.java:119

                    {
                        try
                        {
                            abortIfDraining();

                            if (options.failOnMissingIndex)
                            {
                                Index.Group saiIndexGroup = cfs.indexManager.getIndexGroup(StorageAttachedIndexGroup.GROUP_KEY);
                                if (saiIndexGroup != null)
                                {
                                    IndexDescriptor indexDescriptor = IndexDescriptor.create(descriptor,
                                                                                             cfs.getPartitioner(),
                                                                                             cfs.metadata().comparator);

                                    String keyspace = cfs.getKeyspaceName();
                                    String table = cfs.getTableName();

                                    if (!indexDescriptor.isPerSSTableIndexBuildComplete())
                                        throw new IllegalStateException(String.format("Missing SAI index to import for SSTable %s on %s.%s",
                                                                                      indexDescriptor.sstableDescriptor.toString(),
                                                                                      keyspace,
                                                                                      table));

                                    for (Index index : saiIndexGroup.getIndexes())
                                    {
                                        IndexIdentifier indexIdentifier = new IndexIdentifier(keyspace, table, index.getIndexMetadata().name);
                                        if (!indexDescriptor.isPerColumnIndexBuildComplete(indexIdentifier))
                                            throw new IllegalStateException(String.format("Missing SAI index to import for index %s on %s.%s",
                                                                                          index.getIndexMetadata().name,
                                                                                          keyspace,
                                                                                          table));
                                    }
                                }
                            }

                            if (options.verifySSTables || options.verifyTokens)
                                verifySSTableForImport(descriptor, entry.getValue(), options.verifyTokens, options.verifySSTables, options.extendedVerify);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the SSTable is fully built: rebuild SAI indexes (`nodetool indexupgrade`/rebuild the index or run a full index build) before importing
2. Copy the complete SSTable component set including SAI index files (`.db`, `-CompressionInfo`, SAI per-column/per-sstable files) from a healthy source
3. Take backups only after index builds complete, or run a fresh index build after import on the target
4. If SAI is not needed for the import, drop and recreate the index on the destination after import

Example fix

// before: importing an SSTable with incomplete SAI files
nodetool import -- ks table /data/import
// after: rebuild the SAI index first, then import
nodetool rebuild_index ks table idx
nodetool import -- ks table /data/import

// before import: check SAI per-sstable build completeness marker exists
File saiMarker = new File(importDir, sstableBase + ".db");
if (!hasCompleteSaiComponents(importDir)) {
    throw new IllegalStateException("SAI index components incomplete; rebuild index before import");
}

When it happens

Trigger: Running `nodetool import` (SSTableImporter.importNewSSTables) on an SSTable whose sstable Descriptor has isPerSSTableIndexBuildComplete() == false — i.e., SAI index files are absent or were not finished being built before the SSTable was copied into the import directory.

Common situations: Copying SSTables from a node while an SAI index build/rebuild was still in progress; manually copying only the -Data.db files without the SAI index components; restoring a backup taken mid index-build.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Missing SAI index to import for index %s on %s.%s
• Failed verifying SSTable <descriptor>
• Failed importing SSTables
• Failed adding SSTables
• SSTables import has been aborted

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