{"record":{"id":"53f59113a634b3ea","repo":"juicedata/juicefs","slug":"init-libjfs-failed","errorCode":null,"errorMessage":"Init libjfs failed","messagePattern":"Init libjfs failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java","lineNumber":891,"sourceCode":"              int bytesRead = 0;\n              while ((bytesRead = reader.read(buffer)) != -1) {\n                writer.write(buffer, 0, bytesRead);\n              }\n            }\n            tmp.setLastModified(soTime);\n            tmp.setReadable(true, false);\n            try {\n              File org = new File(dir, name);\n              Files.move(tmp.toPath(), org.toPath(), StandardCopyOption.ATOMIC_MOVE);\n              libFile = org;\n            } catch (Exception ade) {\n              Files.move(tmp.toPath(), libFile.toPath(), StandardCopyOption.ATOMIC_MOVE);\n            }\n          }\n        }\n      }\n    } catch (Exception e) {\n      throw new RuntimeException(\"Init libjfs failed\", e);\n    } finally {\n      if (ins != null) {\n        try {\n          ins.close();\n        } catch (Exception ignore){}\n      }\n    }\n    return libjfsLibraryLoader.load(libFile.getAbsolutePath());\n  }\n\n  private static Libjfs loadExistLib(LibraryLoader<Libjfs> libjfsLibraryLoader, File dir, String name, File libFile) {\n    File currentUserLib = new File(dir, System.getProperty(\"user.name\") + \"-\" + name);\n    if (currentUserLib.exists()) {\n      return libjfsLibraryLoader.load(currentUserLib.getAbsolutePath());\n    } else {\n      return libjfsLibraryLoader.load(libFile.getAbsolutePath());\n    }\n  }","sourceCodeStart":873,"sourceCodeEnd":909,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java#L873-L909","documentation":"loadLibrary() locates the bundled libjfs native library inside the jar for the current platform, copies it to a temporary file (atomically moving a partially written temp file into place), and loads it. Any exception during locating, writing, moving, or opening the library is wrapped in this RuntimeException('Init libjfs failed').","triggerScenarios":"Exception while reading the .so resource from the jar, writing/moving the temp file (ATOMIC_MOVE can fail across filesystems), or during the native load — wrapped as RuntimeException with the original exception as cause.","commonSituations":"Temp directory on a different filesystem than the target so ATOMIC_MOVE fails (AtomicMoveNotSupportedException); disk full; no write permission on the library/cache directory; corrupted or truncated jar missing the native resource.","solutions":["Inspect the 'caused by' exception: it distinguishes resource-missing vs file-write vs move failures.","Ensure java.io.tmpdir and the target lib directory are on the same filesystem (or upgrade the client so ATOMIC_MOVE falls back).","Free disk space and verify write permissions on the temp/cache directory.","Re-download/rebuild the juicefs-hadoop jar if the native resource is missing or the jar is corrupted."],"exampleFix":"// before (AtomicMoveNotSupportedException: /tmp and lib dir on different mounts)\n-Djava.io.tmpdir=/tmp -Djuicefs.lib.dir=/var/lib/juicefs\n// after\n-Djava.io.tmpdir=/var/lib/juicefs/tmp  # same filesystem as lib dir\n","handlingStrategy":"try-catch","validationCode":"java.io.File tmp = new java.io.File(System.getProperty(\"java.io.tmpdir\"));\nif (!tmp.canWrite() || tmp.getUsableSpace() < 256L*1024*1024) {\n  throw new IllegalStateException(\"temp dir unusable for native lib extraction: \" + tmp);\n}","typeGuard":null,"tryCatchPattern":"try { fs = FileSystem.get(uri, conf); } catch (RuntimeException e) { if (\"Init libjfs failed\".equals(e.getMessage())) { LOG.error(\"native lib extraction/load failed\", e.getCause()); } throw e; }","preventionTips":["Keep java.io.tmpdir and the lib target on the same filesystem.","Monitor disk space on temp volumes.","Verify jar integrity (checksum) after distribution.","Run as a user with write access to the temp/cache directories."],"tags":["native-library","file-io","jvm"],"backgroundTag":"module-init-failed","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}