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.

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)

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
• JuiceFS initialized failed for jfs://" + name
• Invalid parameter

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