{"record":{"id":"2978fab00519c96f","repo":"apache/cassandra","slug":"lz4-java-was-unable-to-load-native-libraries-this","errorCode":null,"errorMessage":"lz4-java was unable to load native libraries; this will lower the performance of lz4 (network/sstables/etc.): {}","messagePattern":"lz4-java was unable to load native libraries; this will lower the performance of lz4 \\(network/sstables/etc\\.\\): (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/service/StartupChecks.java","lineNumber":347,"sourceCode":"    {\n        @Override\n        public String name()\n        {\n            return \"lz4_native\";\n        }\n\n        @Override\n        public void execute(StartupChecksConfiguration configuration)\n        {\n            if (configuration.isDisabled(name()))\n                return;\n            try\n            {\n                LZ4Factory.nativeInstance(); // make sure native loads\n            }\n            catch (AssertionError | LinkageError e)\n            {\n                logger.warn(\"lz4-java was unable to load native libraries; this will lower the performance of lz4 (network/sstables/etc.): {}\", Throwables.getRootCause(e).getMessage());\n            }\n        }\n    };\n\n    public static final StartupCheck checkCustomCompressionProviders = new StartupCheck()\n    {\n        @Override\n        public String name()\n        {\n            return \"custom_compression_providers\";\n        }\n\n        @Override\n        public void execute(StartupChecksConfiguration configuration) throws StartupException\n        {\n            if (configuration.isDisabled(name()))\n                return;\n","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StartupChecks.java#L329-L365","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the logged root-cause message to confirm which native library failed to load","Ensure the JVM can extract native libs: point -Djava.io.tmpdir at a writable, exec-permitted directory (not noexec)","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"],"exampleFix":"// before (jvm-server.options)\n-Djava.io.tmpdir=/tmp  # mounted noexec\n\n// after\n-Djava.io.tmpdir=/var/tmp/cassandra  # writable and exec-permitted","handlingStrategy":"try-catch","validationCode":"// Pre-flight: verify lz4 natives load in the target JVM/image\ntry {\n    net.jpountz.lz4.LZ4Factory.nativeInstance();\n    System.out.println(\"lz4 native OK\");\n} catch (AssertionError | LinkageError e) {\n    System.out.println(\"lz4 native unavailable (pure-Java fallback): \" + e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    LZ4Factory.nativeInstance();\n} catch (AssertionError | LinkageError e) {\n    System.out.println(\"lz4 native load failed: \" + Throwables.getRootCause(e).getMessage());\n}","preventionTips":["Test the exact node image + JVM combination on the target architecture before rollout","Ensure java.io.tmpdir is writable and not mounted noexec (natives are extracted there)","Use lz4-java versions with natives for your architecture; upgrade Cassandra if natives are missing for aarch64","Accept pure-Java lz4 only knowingly; measure compression throughput impact"],"tags":["lz4","compression","native-library","performance","startup-checks"],"backgroundTag":"missing-optional-dependency","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}