apache/cassandra · error · ConfigurationException

Failed to instantiate sstable format '%s'

Error message

Failed to instantiate sstable format '%s'

What it means

After validating format options, DatabaseDescriptor invokes each registered format Supplier to instantiate the SSTableFormat; any RuntimeException or Error thrown by the supplier is wrapped in this ConfigurationException naming the format. This converts provider-construction failures (bad option values, missing classes, internal errors) into a single startup-time config error.

Source

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

    }

    private static void applySSTableFormats(Iterable<SSTableFormat.Factory> factories, Config.SSTableConfig sstableFormatsConfig)
    {
        if (sstableFormats != null)
            return;

        validateSSTableFormatFactories(factories);
        ImmutableMap<String, Supplier<SSTableFormat<?, ?>>> providers = validateAndMatchSSTableFormatOptions(factories, sstableFormatsConfig.format);

        ImmutableMap.Builder<String, SSTableFormat<?, ?>> sstableFormatsBuilder = ImmutableMap.builder();
        providers.forEach((name, provider) -> {
            try
            {
                sstableFormatsBuilder.put(name, provider.get());
            }
            catch (RuntimeException | Error ex)
            {
                throw new ConfigurationException(String.format("Failed to instantiate sstable format '%s'", name), ex);
            }
        });
        sstableFormats = sstableFormatsBuilder.build();

        selectedSSTableFormat = getAndValidateWriteFormat(sstableFormats, sstableFormatsConfig.selected_format);

        sstableFormats.values().forEach(SSTableFormat::allComponents); // make sure to reach all supported components for a type so that we know all of them are registered
        logger.info("Supported sstable formats are: {}", sstableFormats.values().stream().map(f -> f.name() + " -> " + f.getClass().getName() + " with singleton components: " + f.allComponents()).collect(Collectors.joining(", ")));
    }

    /**
     * Computes the sum of the 2 specified positive values returning {@code Long.MAX_VALUE} if the sum overflow.
     *
     * @param left  the left operand
     * @param right the right operand
     * @return the sum of the 2 specified positive values of {@code Long.MAX_VALUE} if the sum overflow.
     */
    private static long saturatedSum(long left, long right)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Read the wrapped cause (ex) in the stack trace to see why the format's constructor failed
2. Fix or remove the offending sstable_formats.options entry for that format in cassandra.yaml
3. Restore missing dependency jars or use a format version compatible with your Cassandra version

Example fix

// before (cassandra.yaml)
sstable_formats:
  options:
    bti:
      target_segment_size: "not-a-number"
// after
sstable_formats:
  options:
    bti:
      target_segment_size: 64MiB

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) {
    log.error("SSTable format init failed: {}", e.getMessage(), e.getCause()); // inspect cause
}

When it happens

Trigger: A registered format's Supplier.get() throws while applying its configured options, e.g. invalid sstable_formats.options value for the format, NoClassDefFoundError from a missing dependency jar, or an assertion/internal error inside the format's constructor.

Common situations: Misconfigured format-specific options in cassandra.yaml; incomplete deployment missing a format's dependency classes; incompatible format implementation against the running Cassandra version throwing during init.

Related errors

• Multiple sstable format implementations with the same name %
• %s has authorization enabled which requires %s to enable aut
• %s requires %s
• %s can't be used with %s
• %s does not support %s

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