apache/cassandra · error · ConfigurationException

SSTable format name for %s must be non-empty, lower-case let

Error message

SSTable format name for %s must be non-empty, lower-case letters only string

What it means

SSTable format names become directory suffixes and config keys, so validateSSTableFormatFactories enforces they are non-empty, all-lowercase-letter strings matching ^[a-z]+$. A factory whose name() returns anything else (digits, underscores, uppercase, empty) is rejected with this ConfigurationException.

Source

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

                with = "encryption";
            throw new ConfigurationException("commitlog_disk_access_mode = " + accessModeDirectIoPair.left + " is not supported with " + with + ". Please use 'auto' when unsure.", false);
        }
        else if (!compressOrEncrypt && accessModeDirectIoPair.left != DiskAccessMode.mmap && accessModeDirectIoPair.left != DiskAccessMode.direct)
        {
            throw new ConfigurationException("commitlog_disk_access_mode = " + accessModeDirectIoPair.left + " is not supported. Please use 'auto' when unsure.", false);
        }
    }

    private static void validateSSTableFormatFactories(Iterable<SSTableFormat.Factory> factories)
    {
        Map<String, SSTableFormat.Factory> factoryByName = new HashMap<>();
        for (SSTableFormat.Factory factory : factories)
        {
            if (factory.name() == null)
                throw new ConfigurationException(String.format("SSTable format name in %s cannot be null", factory.getClass().getCanonicalName()));

            if (!factory.name().matches("^[a-z]+$"))
                throw new ConfigurationException(String.format("SSTable format name for %s must be non-empty, lower-case letters only string", factory.getClass().getCanonicalName()));

            SSTableFormat.Factory prev = factoryByName.put(factory.name(), factory);
            if (prev != null)
                throw new ConfigurationException(String.format("Multiple sstable format implementations with the same name %s: %s and %s", factory.name(), factory.getClass().getCanonicalName(), prev.getClass().getCanonicalName()));
        }
    }

    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();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Change the factory's name() to return only lowercase letters, e.g. "myformat" instead of "MyFormat" or "my_format"
2. Remove or replace the offending third-party format factory jar if you don't need the format
3. Rename directories/data references accordingly — the format name is used in file suffixes, so pick the name before creating data

Example fix

// before
public String name() { return "My_Format2"; }
// after
public String name() { return "myformat"; }

if (!String.valueOf(yaml.getOrDefault("partitioner","")).matches("^[a-zA-Z0-9_.$]+$")) throw new IllegalStateException("bad partitioner name");

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* fix class name */ }

When it happens

Trigger: A custom SSTableFormat.Factory returns a name that fails matches("^[a-z]+$") — e.g. "MyFormat", "my_format", "format2", or ""; thrown during format factory registration at startup.

Common situations: Third-party format jars written before this validation existed; authors naming formats with underscores or version suffixes; copy-pasted factory code with a placeholder name.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• SSTable format name in %s cannot be null
• Multiple sstable format implementations with the same name %
• Configuration contains options of unknown sstable formats: %
• Selected sstable format '%s' is not available.
• Failed to instantiate sstable format '%s'

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