apache/cassandra · error · ConfigurationException

Unknown compression options %s

Error message

Unknown compression options %s

What it means

DefaultCompressionProvider.createCompressor() invokes the compressor class's static create(Map) method, then verifies every user-supplied option is in compressor.supportedOptions(). Any option name not recognized by the algorithm (e.g. 'chunk_length_kb' misspelled, or an option belonging to a different algorithm) triggers this ConfigurationException. This guards against silently ignoring compression settings that would not take effect.

Source

Thrown at src/java/org/apache/cassandra/io/compress/DefaultCompressionProvider.java:71

    /**
     * Creates a new compressor instance with the given compression parameters.
     *
     * @param compressionOptions Configuration options for the compressor
     * @return A new ICompressor instance
     * @throws ConfigurationException if the compressor class does not have a valid create method,
     * if there are unknown compression options, or if the compressor creation fails
     */
    @Override
    public ICompressor createCompressor(Class<?> compressorClass, Map<String, String> compressionOptions) throws IllegalStateException
    {
        try
        {
            Method method = compressorClass.getMethod("create", Map.class);
            ICompressor compressor = (ICompressor)method.invoke(null, compressionOptions);
            // Check for unknown options
            for (String provided : compressionOptions.keySet())
                if (!compressor.supportedOptions().contains(provided))
                    throw new ConfigurationException("Unknown compression options " + provided);
            return compressor;
        }
        catch (NoSuchMethodException e)
        {
            throw new ConfigurationException("create method not found", e);
        }
        catch (SecurityException e)
        {
            throw new ConfigurationException("Access forbidden", e);
        }
        catch (IllegalAccessException e)
        {
            throw new ConfigurationException("Cannot access method create in " + compressorClass.getName(), e);
        }
        catch (InvocationTargetException e)
        {
            if (e.getTargetException() instanceof ConfigurationException)
                throw (ConfigurationException) e.getTargetException();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove or correct the unknown option in the compression map; check the valid names with the compressor's supportedOptions() (e.g. chunk_length_kb, crc_check_chance).
2. Cross-check option names against the Cassandra version in use; some options were added/renamed across releases.
3. Use DESCRIBE on a known-good table or the documentation of the specific compressor class to list valid options.

Example fix

// before
CREATE TABLE t (k int PRIMARY KEY) WITH compression = {'sstable_compression':'LZ4Compressor','lz4_chunk_lenght_kb':'64'};
// after
CREATE TABLE t (k int PRIMARY KEY) WITH compression = {'sstable_compression':'LZ4Compressor','chunk_length_kb':'64'};

ICompressor probe = LZ4Compressor.create(Collections.emptyMap());
Set<String> supported = probe.supportedOptions();
for (String key : myOptions.keySet())
    if (!supported.contains(key)) throw new IllegalArgumentException("Unknown option '" + key + "'; supported: " + supported);

try {
    registry.getCompressor(LZ4Compressor.class, options);
} catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Unknown compression options")) log.error("Invalid option: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Creating a table with compression options containing a key not in the target compressor's supportedOptions() — e.g. compression: {'sstable_compression': 'LZ4Compressor', 'crc_check_chance_extra': '1.0'} or passing an unknown map entry directly to getCompressor().

Common situations: Typos in cassandra.yaml compression options; copying options between algorithms (Deflate has no lz4 chunk checksum option); old option names removed in a Cassandra upgrade; case mismatches in option keys.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• compressed_read_ahead_buffer_size_in_kb must be at least 256
• Unknown compressor key '%s' in compressor_providers. Expecte
• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s
• compressed_read_ahead_buffer_size must be at least 256KiB (s

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