juicedata/juicefs · critical · RuntimeException

Init libjfs failed

Error message

Init libjfs failed

What it means

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').

Source

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

              int bytesRead = 0;
              while ((bytesRead = reader.read(buffer)) != -1) {
                writer.write(buffer, 0, bytesRead);
              }
            }
            tmp.setLastModified(soTime);
            tmp.setReadable(true, false);
            try {
              File org = new File(dir, name);
              Files.move(tmp.toPath(), org.toPath(), StandardCopyOption.ATOMIC_MOVE);
              libFile = org;
            } catch (Exception ade) {
              Files.move(tmp.toPath(), libFile.toPath(), StandardCopyOption.ATOMIC_MOVE);
            }
          }
        }
      }
    } catch (Exception e) {
      throw new RuntimeException("Init libjfs failed", e);
    } finally {
      if (ins != null) {
        try {
          ins.close();
        } catch (Exception ignore){}
      }
    }
    return libjfsLibraryLoader.load(libFile.getAbsolutePath());
  }

  private static Libjfs loadExistLib(LibraryLoader<Libjfs> libjfsLibraryLoader, File dir, String name, File libFile) {
    File currentUserLib = new File(dir, System.getProperty("user.name") + "-" + name);
    if (currentUserLib.exists()) {
      return libjfsLibraryLoader.load(currentUserLib.getAbsolutePath());
    } else {
      return libjfsLibraryLoader.load(libFile.getAbsolutePath());
    }
  }

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Inspect the 'caused by' exception: it distinguishes resource-missing vs file-write vs move failures.
2. Ensure java.io.tmpdir and the target lib directory are on the same filesystem (or upgrade the client so ATOMIC_MOVE falls back).
3. Free disk space and verify write permissions on the temp/cache directory.
4. Re-download/rebuild the juicefs-hadoop jar if the native resource is missing or the jar is corrupted.

Example fix

// before (AtomicMoveNotSupportedException: /tmp and lib dir on different mounts)
-Djava.io.tmpdir=/tmp -Djuicefs.lib.dir=/var/lib/juicefs
// after
-Djava.io.tmpdir=/var/lib/juicefs/tmp  # same filesystem as lib dir

java.io.File tmp = new java.io.File(System.getProperty("java.io.tmpdir"));
if (!tmp.canWrite() || tmp.getUsableSpace() < 256L*1024*1024) {
  throw new IllegalStateException("temp dir unusable for native lib extraction: " + tmp);
}

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

When it happens

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

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

Related errors

• StubLoader load failed
• JuiceFS initialized failed for jfs://" + name
• Invalid parameter

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