apache/cassandra · error · ConfigurationException

Unknown compressor key '%s' in compressor_providers. Expecte

Error message

Unknown compressor key '%s' in compressor_providers. Expected a built-in compressor's fully qualified class name, simple class name, or abbreviation: %s

What it means

registerProviders() validates every key in the compressor_providers map against the set of built-in compressor identifiers: fully qualified class names, simple class names, and abbreviations. Any key outside this set is rejected because there is no built-in algorithm it could configure a provider for. This prevents typos and unsupported algorithms from being silently ignored at startup.

Source

Thrown at src/java/org/apache/cassandra/io/compress/CompressorRegistry.java:227

     * @throws ConfigurationException if a provider fails to initialize and fallback is not enabled
     */
    public void registerProviders(Map<String, ParameterizedClass> providerOptions)
    {
        if (providerOptions == null)
            return;

        Set<String> validKeys = new HashSet<>();
        for (CompressorType type : CompressorType.values())
        {
            validKeys.add(type.compressorClassName);
            validKeys.add(type.simpleName);
            validKeys.add(type.abbreviation);
        }

        for (String key : providerOptions.keySet())
        {
            if (!validKeys.contains(key))
                throw new ConfigurationException("Unknown compressor key '" + key + "' in compressor_providers. " +
                                                 "Expected a built-in compressor's fully qualified class name, simple class name, " +
                                                 "or abbreviation: " + validKeys);
        }

        for (CompressorType type : CompressorType.values())
        {
            ParameterizedClass providerConfig = findProviderConfig(providerOptions, type);
            if (providerConfig == null)
            {
                compressionProviders.put(type.compressorClassName, DEFAULT_COMPRESSION_PROVIDER);
            }
            else
            {
                AbstractCompressionProvider provider = resolveProvider(providerConfig);
                compressionProviders.put(type.compressorClassName, provider);
                logger.info("Adding '{}' provider for '{}'", provider.getClass().getName(), type.compressorClassName);
            }
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Change the key to a valid built-in identifier: the FQCN (e.g. org.apache.cassandra.io.compress.LZ4Compressor), the simple name (LZ4Compressor), or the abbreviation (LZ4) as listed in the exception message.
Check the exception's validKeys list and copy the exact spelling from it.
If you need an algorithm not in the list, you cannot add it via compressor_providers; use a compression provider that substitutes a built-in class instead.
Strip stray whitespace and fix casing in the YAML key.

Example fix

// before
cassandra.yaml: compressor_providers: { brotli: { class_name: com.example.BrotliProvider } }
// after
cassandra.yaml: compressor_providers: { LZ4: { class_name: com.example.BrotliProvider } }

Defensive patterns

Strategy: validation

Validate before calling

Set<String> valid = new HashSet<>();
for (CompressorType t : CompressorType.values()) { valid.add(t.compressorClassName); valid.add(t.simpleName); valid.add(t.abbreviation); }
for (String key : providerOptions.keySet()) if (!valid.contains(key)) throw new IllegalArgumentException("Unknown compressor key: " + key);

Try / catch

try {
    registry.registerProviders(cfg.compressorProviders);
} catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Unknown compressor key")) log.error("Fix compressor_providers key; valid: {}", e.getMessage());
    throw e;
}

Prevention

Copy compressor keys exactly from CompressorType values (FQCN, simple name, or abbreviation)
Trim whitespace and match casing in cassandra.yaml keys
Do not invent new algorithm keys; compressor_providers only configures providers for built-in algorithms
Validate the YAML against the valid key list before deploying

When it happens

Trigger: Calling CompressorRegistry.registerProviders(Map<String, ParameterizedClass>) (or setting compressor_providers in cassandra.yaml) with a key that is not a built-in compressor's FQCN, simple name, or abbreviation — e.g. 'brotli', 'LZ4Compressor ' with trailing space, or 'lz4hc'.

Common situations: Typos like 'LZ' instead of 'LZ4'; adding a third-party algorithm key assuming providers can register new algorithms; copying keys from documentation of a different Cassandra version with different abbreviations; extra whitespace or case errors like 'lz4' vs 'LZ4'.

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

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