{"record":{"id":"bf1ef0c7eb8aea39","repo":"apache/hadoop","slug":"lz4-java-library-is-not-available-lz4compressor-h","errorCode":null,"errorMessage":"lz4-java library is not available: Lz4Compressor has not been loaded. You need to add lz4-java.jar to your CLASSPATH. {}","messagePattern":"lz4-java library is not available: Lz4Compressor has not been loaded\\. You need to add lz4-java\\.jar to your CLASSPATH\\. (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/compress/lz4/Lz4Compressor.java","lineNumber":74,"sourceCode":"  /**\n   * Creates a new compressor.\n   *\n   * @param directBufferSize size of the direct buffer to be used.\n   * @param useLz4HC use high compression ratio version of lz4, \n   *                 which trades CPU for compression ratio.\n   */\n  public Lz4Compressor(int directBufferSize, boolean useLz4HC) {\n    this.directBufferSize = directBufferSize;\n\n    try {\n      LZ4Factory lz4Factory = LZ4Factory.fastestInstance();\n      if (useLz4HC) {\n        lz4Compressor = lz4Factory.highCompressor();\n      } else {\n        lz4Compressor = lz4Factory.fastCompressor();\n      }\n    } catch (AssertionError t) {\n      throw new RuntimeException(\"lz4-java library is not available: \" +\n              \"Lz4Compressor has not been loaded. You need to add \" +\n              \"lz4-java.jar to your CLASSPATH. \" + t, t);\n    }\n\n    uncompressedDirectBuf = ByteBuffer.allocateDirect(directBufferSize);\n\n    // Compression is guaranteed to succeed if 'dstCapacity' >=\n    // LZ4_compressBound(srcSize)\n    // whereas LZ4_compressBound(isize) is (isize) + ((isize)/255) + 16)\n    this.dstCapacity = (directBufferSize) + ((directBufferSize) / 255) + 16;\n\n    compressedDirectBuf = ByteBuffer.allocateDirect(this.dstCapacity);\n    compressedDirectBuf.position(this.dstCapacity);\n  }\n\n  /**\n   * Creates a new compressor.\n   *","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/compress/lz4/Lz4Compressor.java#L56-L92","documentation":"Lz4Compressor's constructor delegates to net.jpountz.lz4's LZ4Factory.fastestInstance() to obtain a compressor. When the lz4-java runtime cannot instantiate any implementation (jar missing, unusable natives, incompatible build), the factory throws AssertionError, which the constructor catches and rethrows as a RuntimeException telling you to add lz4-java.jar to the CLASSPATH. It is an environment/classpath failure, not a code-logic bug, and it fails at construction time, before any compression happens.","triggerScenarios":"new Lz4Compressor(bufferSize) (or Lz4Codec creating its compressor) on a JVM where LZ4Factory.fastestInstance() cannot load an implementation: lz4-java.jar absent from the classpath, a shaded uber-jar that stripped net.jpountz classes or natives, or native artifacts for a wrong platform so even the JNI binding fails the factory's self-check.","commonSituations":"Slimmed-down deployments (hadoop-common without its optional lz4-java dependency); application shading (maven-shade minimizeJar) excluding net.jpountz.lz4; version conflicts between hadoop-common and a separately pinned lz4-java; running on an uncommon architecture where bundled natives do not load.","solutions":["Add the lz4-java dependency explicitly (org.lz4:lz4-java) at the version matching your hadoop-common distribution, and confirm it appears on the final classpath (mvn dependency:tree / printed classpath).","If shading, keep net.jpountz.lz4 (and its native resources) in the uber-jar; exclude minimizeJar effects for that package.","Drop conflicting/older lz4 artifacts so LZ4Factory resolves exactly one implementation.","Smoke-test at startup: construct Lz4Compressor once so deployment fails fast with the clear message instead of mid-job."],"exampleFix":"// before\nCompressor c = new Lz4Compressor(64 * 1024); // RuntimeException if lz4-java absent\n\n// after\ntry {\n  Class.forName(\"net.jpountz.lz4.LZ4Factory\");\n} catch (ClassNotFoundException cnfe) {\n  throw new IllegalStateException(\n      \"lz4-java.jar missing from classpath; add org.lz4:lz4-java\", cnfe);\n}\nCompressor c = new Lz4Compressor(64 * 1024);","handlingStrategy":"validation","validationCode":"static boolean lz4Available() {\n  try {\n    Class.forName(\"net.jpountz.lz4.LZ4Factory\");\n    LZ4Factory.fastestInstance(); // force binding resolution now\n    return true;\n  } catch (AssertionError | ClassNotFoundException | NoClassDefFoundError t) {\n    return false;\n  }\n}\n\nif (!lz4Available()) {\n  throw new IllegalStateException(\"add org.lz4:lz4-java to the classpath\");\n}\nnew Lz4Compressor(64 * 1024);","typeGuard":null,"tryCatchPattern":"try {\n  new Lz4Compressor(64 * 1024);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"lz4-java library is not available\")) {\n    // classpath defect: fix deployment, do not retry\n    throw new IllegalStateException(\"lz4-java missing on \" + nodeName, e);\n  }\n  throw e;\n}","preventionTips":["Declare org.lz4:lz4-java at the version matching your hadoop-common build.","When shading, keep net.jpountz.lz4 classes and native resources; verify with 'jar tf app.jar | grep jpountz'.","Resolve duplicate lz4 artifacts with dependency:tree so LZ4Factory binds one implementation.","Health-check codec construction at service startup to fail fast on slim nodes."],"tags":["lz4","compression","classpath","missing-dependency","hadoop","native-library"],"backgroundTag":"missing-classpath-dependency","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}