juicedata/juicefs · critical · RuntimeException

StubLoader load failed

Error message

StubLoader load failed

What it means

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.

Solutions

1. Read StubLoader.getFailureCause() (shown as the cause) — it names the real load problem.
2. Confirm the OS/arch has a bundled build; use STATIC=1 or a musl-compatible build on Alpine.
3. Clear the stale extracted library in java.io.tmpdir and retry.
4. Ensure the temp directory is writable and TMPDIR points somewhere valid; install missing shared libraries (ldd on the extracted .so).

Example fix

# before: failure extracting to /tmp (read-only)
TMPDIR=/tmp java ...
// after
TMPDIR=/var/tmp java ...  # or fix /tmp permissions

// preflight: confirm temp dir is writable
java.io.File tmp = new java.io.File(System.getProperty("java.io.tmpdir"));
if (!tmp.canWrite()) throw new IllegalStateException("TMPDIR not writable: " + tmp);

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; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Init libjfs failed
• Invalid parameter
• JuiceFS initialized failed for jfs://" + name

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/f2b86f031228af6d. Report an issue: GitHub.

Appendix: source

Thrown at sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java:786

      try {
        Thread.interrupted();
        Method load = clazz.getDeclaredMethod("load");
        load.setAccessible(true);
        load.invoke(null);

        Field loaded = clazz.getDeclaredField("loaded");
        loaded.setAccessible(true);
        loaded.set(null, true);

        Field failureCause = clazz.getDeclaredField("failureCause");
        failureCause.setAccessible(true);
        failureCause.set(null, null);
      } catch (Throwable e) {
      }
    }

    if (StubLoader.getFailureCause() != null) {
      throw new RuntimeException("StubLoader load failed", StubLoader.getFailureCause());
    }
  }

  public static Libjfs loadLibrary() {
    initStubLoader();

    LibraryLoader<Libjfs> libjfsLibraryLoader = LibraryLoader.create(Libjfs.class);
    libjfsLibraryLoader.failImmediately();

    String osId = "so";
    String archId = "amd64";
    String resourceFormat = "libjfs-%s.%s.gz";
    String nameFormat = "libjfs-%s.%s.%s";

    File dir = new File("/tmp");
    String os = System.getProperty("os.name");
    String arch = System.getProperty("os.arch");
    if (arch.contains("aarch64")) {

View on GitHub (pinned to c9a67b23e8)