{"record":{"id":"f2b86f031228af6d","repo":"juicedata/juicefs","slug":"stubloader-load-failed","errorCode":null,"errorMessage":"StubLoader load failed","messagePattern":"StubLoader load failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java","lineNumber":786,"sourceCode":"      try {\n        Thread.interrupted();\n        Method load = clazz.getDeclaredMethod(\"load\");\n        load.setAccessible(true);\n        load.invoke(null);\n\n        Field loaded = clazz.getDeclaredField(\"loaded\");\n        loaded.setAccessible(true);\n        loaded.set(null, true);\n\n        Field failureCause = clazz.getDeclaredField(\"failureCause\");\n        failureCause.setAccessible(true);\n        failureCause.set(null, null);\n      } catch (Throwable e) {\n      }\n    }\n\n    if (StubLoader.getFailureCause() != null) {\n      throw new RuntimeException(\"StubLoader load failed\", StubLoader.getFailureCause());\n    }\n  }\n\n  public static Libjfs loadLibrary() {\n    initStubLoader();\n\n    LibraryLoader<Libjfs> libjfsLibraryLoader = LibraryLoader.create(Libjfs.class);\n    libjfsLibraryLoader.failImmediately();\n\n    String osId = \"so\";\n    String archId = \"amd64\";\n    String resourceFormat = \"libjfs-%s.%s.gz\";\n    String nameFormat = \"libjfs-%s.%s.%s\";\n\n    File dir = new File(\"/tmp\");\n    String os = System.getProperty(\"os.name\");\n    String arch = System.getProperty(\"os.arch\");\n    if (arch.contains(\"aarch64\")) {","sourceCodeStart":768,"sourceCodeEnd":804,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java#L768-L804","documentation":"Before loading the native library, the client runs StubLoader, which extracts/loads the bundled native stub and records any failure cause. If a failure cause is still set after initStubLoader(), this RuntimeException wraps it, meaning the bundled native library could not be loaded into the JVM.","triggerScenarios":"initStubLoader() fails to extract or System.load the bundled libjfs for the current OS/architecture; a previous load attempt left a non-null failure cause.","commonSituations":"Unsupported OS/architecture (no bundled binary, e.g. Alpine musl or ARM without a matching build); missing system dependencies for the .so; temp directory not writable so extraction fails; stale cached native lib in the temp dir.","solutions":["Read StubLoader.getFailureCause() (shown as the cause) — it names the real load problem.","Confirm the OS/arch has a bundled build; use STATIC=1 or a musl-compatible build on Alpine.","Clear the stale extracted library in java.io.tmpdir and retry.","Ensure the temp directory is writable and TMPDIR points somewhere valid; install missing shared libraries (ldd on the extracted .so)."],"exampleFix":"# before: failure extracting to /tmp (read-only)\nTMPDIR=/tmp java ...\n// after\nTMPDIR=/var/tmp java ...  # or fix /tmp permissions\n","handlingStrategy":"try-catch","validationCode":"// preflight: confirm temp dir is writable\njava.io.File tmp = new java.io.File(System.getProperty(\"java.io.tmpdir\"));\nif (!tmp.canWrite()) throw new IllegalStateException(\"TMPDIR not writable: \" + tmp);","typeGuard":null,"tryCatchPattern":"try { fs = FileSystem.get(uri, conf); } catch (RuntimeException e) { if (\"StubLoader load failed\".equals(e.getMessage())) { LOG.error(\"native stub load failed\", e.getCause()); /* fix OS/arch/libs per cause */ } throw e; }","preventionTips":["Check e.getCause() first — it names the real problem.","Match the client build to OS/arch (musl vs glibc, amd64 vs arm64).","Keep TMPDIR writable and clear stale extracted libraries after upgrades."],"tags":["native-library","jvm","loading"],"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-14T05:17:10.506Z"}