apache/cassandra · error · ConfigurationException

Configuration contains options of unknown sstable formats: %

Error message

Configuration contains options of unknown sstable formats: %s

What it means

validateAndMatchSSTableFormatOptions compares the sstable format option keys in cassandra.yaml against the names of registered format providers; any key with no matching provider causes this ConfigurationException. Cassandra requires every format listed in the options map to correspond to a factory that was actually registered.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1957

        }
    }

    private static ImmutableMap<String, Supplier<SSTableFormat<?, ?>>> validateAndMatchSSTableFormatOptions(Iterable<SSTableFormat.Factory> factories, Map<String, Map<String, String>> options)
    {
        ImmutableMap.Builder<String, Supplier<SSTableFormat<?, ?>>> providersBuilder = ImmutableMap.builder();
        if (options == null)
            options = ImmutableMap.of();
        for (SSTableFormat.Factory factory : factories)
        {
            Map<String, String> formatOptions = options.getOrDefault(factory.name(), ImmutableMap.of());
            providersBuilder.put(factory.name(), () -> factory.getInstance(ImmutableMap.copyOf(formatOptions)));
        }
        ImmutableMap<String, Supplier<SSTableFormat<?, ?>>> providers = providersBuilder.build();
        if (options != null)
        {
            Sets.SetView<String> unknownFormatNames = Sets.difference(options.keySet(), providers.keySet());
            if (!unknownFormatNames.isEmpty())
                throw new ConfigurationException(String.format("Configuration contains options of unknown sstable formats: %s", unknownFormatNames));
        }
        return providers;
    }

    private static SSTableFormat<?, ?> getAndValidateWriteFormat(Map<String, SSTableFormat<?, ?>> sstableFormats, String selectedFormatName)
    {
        SSTableFormat<?, ?> selectedFormat;
        if (StringUtils.isBlank(selectedFormatName))
            selectedFormatName = BigFormat.NAME;
        selectedFormat = sstableFormats.get(selectedFormatName);
        if (selectedFormat == null)
            throw new ConfigurationException(String.format("Selected sstable format '%s' is not available.", selectedFormatName));

        getStorageCompatibilityMode().validateSstableFormat(selectedFormat);

        return selectedFormat;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove the unknown format's entry from sstable_formats.options in cassandra.yaml
2. Correct the format-name key so it matches a registered format (e.g. 'big' or 'bti')
3. Restore the format-provider jar to the classpath if the format is still wanted

Example fix

// before (cassandra.yaml)
sstable_formats:
  options:
    btx:
      some_option: 1
// after
sstable_formats:
  options:
    bti:
      some_option: 1

Set<String> registered = Set.of("big", "bti");
Set<String> configured = yamlSstableFormatOptions.keySet();
if (!registered.containsAll(configured))
    throw new IllegalArgumentException("Unknown sstable formats: " + Sets.difference(configured, registered));

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Configuration contains options of unknown sstable formats"))
        fixYamlOptions();
}

When it happens

Trigger: cassandra.yaml contains an sstable_formats.options entry keyed by a format name that is not registered, e.g. options for a custom format whose jar was removed, or a typo in the format key, after downgrading from a version that shipped an extra format.

Common situations: Downgrade/upgrade across Cassandra versions where a format was removed; typo in the format key under sstable_formats options; custom format jar missing from the classpath while its config options remain in cassandra.yaml.

Related errors

• Selected sstable format '%s' is not available.
• %s has authorization enabled which requires %s to enable aut
• SSTable format name in %s cannot be null
• SSTable format name for %s must be non-empty, lower-case let
• Multiple sstable format implementations with the same name %

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