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

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
Defensive patterns

Strategy: try-catch

Validate before calling

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 / catch

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

Prevention

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

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

Appendix: 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)