apache/cassandra · error · ConfigurationException

Selected sstable format

Error message

Selected sstable format '%s' is not available when in storage compatibility mode '%s'.

What it means

StorageCompatibilityMode.validateSstableFormat rejects an SSTable format selection that is incompatible with the active storage compatibility mode. Specifically, selecting BTI format while running in CASSANDRA_4 compatibility mode throws this ConfigurationException, since BTI is not readable/writable when emulating 4.x storage.

Solutions

Either change the table's sstable format back to 'bige' while in CASSANDRA_4 mode
Or complete the storage compatibility-mode upgrade (switch mode off CASSANDRA_4) before using BTI
Check cassandra.yaml / schema for 'bti' occurrences and remove them until the mode is upgraded
Plan the upgrade path: finish 4.x compatibility phase, then enable BTI per table

Example fix

// before (cassandra.yaml / schema)
sstable_format: bti   # with storage_compatibility_mode: CASSANDRA_4
// after
sstable_format: bige  # then switch compatibility mode before using bti

Defensive patterns

Strategy: validation

Validate before calling

if ("bti".equalsIgnoreCase(selectedFormat) && StorageCompatibilityMode.current() == StorageCompatibilityMode.CASSANDRA_4)
    throw new ConfigurationException("bti format requires exiting CASSANDRA_4 compatibility mode");

Try / catch

try { mode.validateSstableFormat(format); } catch (ConfigurationException e) { logger.error(e.getMessage()); /* fall back to bige or abort startup */ }

Prevention

Audit cassandra.yaml and schemas for 'bti' before planning a 4.x upgrade
Only enable BTI after completing compatibility-mode progression
Document the upgrade order: bige on 4-mode → switch mode → bti
Validate config in CI before rolling out upgrades

When it happens

Trigger: Setting sstable format to 'bti' in cassandra.yaml or via CREATE TABLE options while storage compatibility mode is CASSANDRA_4, or upgrading config files that enable BTI before switching the compatibility mode.

Common situations: Upgrades from Cassandra 4.x where operators pre-configure BTI tables, mixed-version clusters pinned in CASSANDRA_4 mode, or copy-pasted table options from newer clusters.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/StorageCompatibilityMode.java:84

    public static StorageCompatibilityMode current()
    {
        return DatabaseDescriptor.getStorageCompatibilityMode();
    }

    public boolean disabled()
    {
        return this == NONE;
    }

    public boolean isBefore(int major)
    {
        return this.major < major;
    }

    public void validateSstableFormat(SSTableFormat<?, ?> selectedFormat)
    {
        if (selectedFormat.name().equals(BtiFormat.NAME) && this == StorageCompatibilityMode.CASSANDRA_4)
            throw new ConfigurationException(String.format("Selected sstable format '%s' is not available when in storage compatibility mode '%s'.",
                                                           selectedFormat.name(),
                                                           this));
    }
}

View on GitHub (pinned to 88fd0f6a0e)