apache/cassandra · error · ConfigurationException

SSTable format name in %s cannot be null

Error message

SSTable format name in %s cannot be null

What it means

When registering SSTable format factories, DatabaseDescriptor.validateSSTableFormatFactories requires every factory to expose a non-null format name, since the name is the lookup key used by config (sstable.format) and manifest parsing. A factory returning null from name() is a programming/config error and aborts startup.

Source

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

            else if (null != getCommitLogCompression())
                with = "compression";
            else
                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());

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Fix the custom factory implementation so name() returns a non-null identifier (e.g. "btreeplus"-style lowercase string)
2. If the factory comes from a third-party jar, upgrade to a version with a proper name() or remove the jar/lib entry
3. Check the class named in the message and set its format name field/config so name() is populated

Example fix

// before
public class MyFormatFactory implements SSTableFormat.Factory {
    public String name() { return myNameField; } // null when unset
}
// after
public class MyFormatFactory implements SSTableFormat.Factory {
    public String name() { return myNameField != null ? myNameField : "myformat"; }
}

if (yaml.get("partitioner") == null) throw new IllegalStateException("set partitioner before startup");

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* inspect and fix yaml */ }

When it happens

Trigger: A custom SSTableFormat.Factory on the classpath (loaded via the sstable format factory mechanism) returns null from name(); the loop over factories detects it and throws ConfigurationException naming the factory class.

Common situations: Developing a third-party SSTable format whose name() isn't implemented or returns null; a factory built reflectively from misconfigured parameters leaving the name field unset.

Related errors

• SSTable format name for %s must be non-empty, lower-case let
• 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/4bda68495a37b5e9. Report an issue: GitHub.