apache/cassandra · warning

lz4-java was unable to load native libraries; this will…

Error message

lz4-java was unable to load native libraries; this will lower the performance of lz4 (network/sstables/etc.): {}

What it means

A WARN log (not an exception) from the checkLz4 startup check's execute(). Cassandra calls LZ4Factory.nativeInstance() to verify lz4-java's native library loads; on AssertionError or LinkageError it logs that native lz4 could not be loaded (with the root cause message) and the pure-Java fallback is used, lowering performance of network and sstable compression.

Solutions

1. Check the logged root-cause message to confirm which native library failed to load
2. Ensure the JVM can extract native libs: point -Djava.io.tmpdir at a writable, exec-permitted directory (not noexec)
3. Use a lz4-java build with natives for your architecture (or upgrade Cassandra's lz4 dependency), or accept the pure-Java fallback knowing compression throughput will be lower

Example fix

// before (jvm-server.options)
-Djava.io.tmpdir=/tmp  # mounted noexec

// after
-Djava.io.tmpdir=/var/tmp/cassandra  # writable and exec-permitted

// Pre-flight: verify lz4 natives load in the target JVM/image
try {
    net.jpountz.lz4.LZ4Factory.nativeInstance();
    System.out.println("lz4 native OK");
} catch (AssertionError | LinkageError e) {
    System.out.println("lz4 native unavailable (pure-Java fallback): " + e);
}

try {
    LZ4Factory.nativeInstance();
} catch (AssertionError | LinkageError e) {
    System.out.println("lz4 native load failed: " + Throwables.getRootCause(e).getMessage());
}

When it happens

Trigger: checkLz4.execute() at node startup when LZ4Factory.nativeInstance() throws AssertionError or LinkageError — typically the lz4-java native .so for the platform/architecture is missing or unloadable.

Common situations: Running on an architecture without a prebuilt lz4 native (e.g. aarch64 in older lz4-java); containers with stripped native libs; JVMs where JNI extraction to java.io.tmpdir fails (noexec tmp, read-only fs); incompatible lz4-java version vs JVM.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• jemalloc shared library could not be preloaded to speed up…
• Cannot initialize class
• Compression provider
• Invalid compressor type
• Provided frame does not appear to be LZ4 compressed

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/StartupChecks.java:347

    {
        @Override
        public String name()
        {
            return "lz4_native";
        }

        @Override
        public void execute(StartupChecksConfiguration configuration)
        {
            if (configuration.isDisabled(name()))
                return;
            try
            {
                LZ4Factory.nativeInstance(); // make sure native loads
            }
            catch (AssertionError | LinkageError e)
            {
                logger.warn("lz4-java was unable to load native libraries; this will lower the performance of lz4 (network/sstables/etc.): {}", Throwables.getRootCause(e).getMessage());
            }
        }
    };

    public static final StartupCheck checkCustomCompressionProviders = new StartupCheck()
    {
        @Override
        public String name()
        {
            return "custom_compression_providers";
        }

        @Override
        public void execute(StartupChecksConfiguration configuration) throws StartupException
        {
            if (configuration.isDisabled(name()))
                return;

View on GitHub (pinned to 88fd0f6a0e)