apache/cassandra · error · ConfigurationException

Failed to initialize compression provider

Error message

Failed to initialize compression provider %s

What it means

When a custom compression provider fails to initialize or reports isHealthy()==false, Cassandra falls back to DefaultCompressionProvider — unless the provider config sets fail_on_missing_provider=true. In that strict mode the fallback is disabled and resolveProvider() throws this ConfigurationException instead, aborting startup/registration.

Solutions

1. Fix the underlying provider failure: check the preceding WARN log ('Failed to initialize specified compression provider') for the root cause (class not found, init exception, unhealthy).
2. Set fail_on_missing_provider=false (or remove it) in the provider's parameters to allow fallback to DefaultCompressionProvider.
3. Correct the class_name to a loadable AbstractCompressionProvider implementation on the classpath.
4. If the provider requires external resources (native libs, services), install/verify them before starting Cassandra.

Example fix

// before
cassandra.yaml: compressor_providers: { LZ4: { class_name: com.example.FastProvider, parameters: { fail_on_missing_provider: true } } }
// after
cassandra.yaml: compressor_providers: { LZ4: { class_name: com.example.FastProvider, parameters: { fail_on_missing_provider: false } } }

ParameterizedClass pc = ...;
boolean strict = Boolean.parseBoolean(pc.parameters.getOrDefault("fail_on_missing_provider", "false"));
try { Class.forName(pc.class_name); } catch (ClassNotFoundException e) { if (strict) throw e; else log.warn("Provider missing, default will be used"); }

try {
    registry.registerProviders(providers);
} catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Failed to initialize compression provider")) {
        log.warn("Falling back to default compression provider");
    } else throw e;
}

When it happens

Trigger: resolveProvider() called with a provider whose class cannot be loaded/instantiated, whose init() throws, or whose isHealthy() returns false, while the provider parameters contain fail_on_missing_provider=true (or FAIL_ON_MISSING_PROVIDER set truthy).

Common situations: Production setups that must not silently fall back from a hardware-accelerated provider to the software default; misconfigured provider class_name or provider init parameters (e.g. missing native library) combined with strict fail-on-missing mode.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Can not initialize CMS without any seeds
• Cannot create CompressionParams for stored parameters
• Cannot find configured row cache provider class
• Cannot locate . If this is a local file, please confirm…
• Cannot replace a live node...

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

Appendix: source

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

            }
            else
            {
                logger.warn("Compression provider {} is not healthy, attempting fallback.", providerConfig.class_name);
            }
        }
        catch (Throwable e)
        {
            logger.warn("Failed to initialize specified compression provider {}. Will attempt fallback to default if enabled.",
                        providerConfig.class_name,
                        e);
        }

        boolean failOnMissingProvider = Boolean.parseBoolean(p.getOrDefault(FAIL_ON_MISSING_PROVIDER, Boolean.FALSE.toString()));

        if (!failOnMissingProvider)
            return DEFAULT_COMPRESSION_PROVIDER;

        throw new ConfigurationException("Failed to initialize compression provider " + providerConfig);
    }
}

View on GitHub (pinned to 88fd0f6a0e)