apache/cassandra · error · ConfigurationException

Missing sub-option ' ' for the 'compression' option.

Error message

Missing sub-option '%s' for the 'compression' option.

What it means

CompressionParams.fromMap requires a 'class' sub-option (the sstable compression algorithm) whenever compression is enabled and any options are given. If options are present and enabled but the class is missing, a ConfigurationException is thrown.

Solutions

  1. Add the compression class, e.g. compression = {'class': 'LZ4Compressor', 'chunk_length_in_kb': '16'}
  2. If you intend to disable compression, set 'enabled': 'false' and remove other options
  3. Verify map-merging code does not drop the 'class' entry

Example fix

// before
compression = {'chunk_length_in_kb': '16'}
// after
compression = {'class': 'LZ4Compressor', 'chunk_length_in_kb': '16'}
Defensive patterns

Strategy: validation

Validate before calling

if (!opts.isEmpty() && !"false".equalsIgnoreCase(opts.getOrDefault("enabled", "true")) && !opts.containsKey("class"))
    throw new IllegalArgumentException("compression options require a 'class' sub-option when enabled");

Type guard

boolean hasCompressionClass(Map<String,String> m) { return m.containsKey("class") && !m.get("class").trim().isEmpty(); }

Try / catch

try { compressionParams = CompressionParams.fromMap(opts); } catch (ConfigurationException e) { if (e.getMessage().contains("Missing sub-option")) { /* add class key */ } throw e; }

Prevention

When it happens

Trigger: CREATE TABLE with compression = {'chunk_length_in_kb': '16'} and no 'class' key; programmatic fromMap with enabled=true and options but no compression class.

Common situations: Users copying chunk_length/other tuning options from examples while omitting the class; scripts that strip the class key during map manipulation.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/schema/CompressionParams.java:95

                                                                       1024 * 4,
                                                                       Integer.MAX_VALUE,
                                                                       DEFAULT_MIN_COMPRESS_RATIO,
                                                                       Collections.emptyMap());

    private final ICompressor sstableCompressor;
    private final int chunkLength;
    private final int maxCompressedLength;  // In content we store max length to avoid rounding errors causing compress/decompress mismatch.
    private final double minCompressRatio;  // In configuration we store min ratio, the input parameter.
    private final ImmutableMap<String, String> otherOptions; // Unrecognized options, can be used by the compressor

    public static CompressionParams fromMap(Map<String, String> opts)
    {
        Map<String, String> options = copyOptions(opts);

        String sstableCompressionClass;

        if (!opts.isEmpty() && isEnabled(opts) && !options.containsKey(CLASS))
            throw new ConfigurationException(format("Missing sub-option '%s' for the 'compression' option.", CLASS));

        if (!removeEnabled(options) && !options.isEmpty())
            throw new ConfigurationException(format("If the '%s' option is set to false no other options must be specified", ENABLED));
        else
            sstableCompressionClass = removeSSTableCompressionClass(options);

        int chunkLength = removeChunkLength(options);
        double minCompressRatio = removeMinCompressRatio(options);

        CompressionParams cp = new CompressionParams(sstableCompressionClass, options, chunkLength, minCompressRatio);
        cp.validate();

        return cp;
    }

    public Class<? extends ICompressor> klass()
    {
        return sstableCompressor.getClass();

View on GitHub (pinned to 88fd0f6a0e)