juicedata/juicefs · critical · IOException

JuiceFS initialized failed for jfs://" + name

Error message

JuiceFS initialized failed for jfs://" + name

What it means

After assembling the JSON configuration (credentials, access log, subdir, etc.), the Java client calls the native function jfs_init. This error is thrown when the native library returns a handle <= 0, meaning the JuiceFS core failed to initialize the volume (bad metadata URL, failed storage login, unknown volume name, etc.). The native-side error details are logged separately.

Source

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

    obj.put("readahead", getConf(conf, "max-readahead", "0"));
    obj.put("pushGateway", getConf(conf, "push-gateway", ""));
    obj.put("pushInterval", getConf(conf, "push-interval", "10"));
    obj.put("pushAuth", getConf(conf, "push-auth", ""));
    obj.put("pushLabels", getConf(conf, "push-labels", ""));
    obj.put("pushGraphite", getConf(conf, "push-graphite", ""));
    obj.put("pushRemoteWrite", getConf(conf, "push-remote-write", ""));
    obj.put("pushRemoteWriteAuth", getConf(conf, "push-remote-write-auth", ""));
    obj.put("guidMask", getConf(conf, "guid-mask", ""));
    obj.put("fastResolve", Boolean.valueOf(getConf(conf, "fast-resolve", "true")));
    obj.put("noUsageReport", Boolean.valueOf(getConf(conf, "no-usage-report", "false")));
    obj.put("freeSpace", getConf(conf, "free-space", "0.1"));
    obj.put("accessLog", getConf(conf, "access-log", ""));
    obj.put("superFs", asSuperFs);
    obj.put("subdir", subdir);
    String jsonConf = obj.toString(2);
    handle = lib.jfs_init(credential, crdSize, name, jsonConf, user, groupStr, superuser, supergroup);
    if (handle <= 0) {
      throw new IOException("JuiceFS initialized failed for jfs://" + name);
    }
    if (isBackGroundTask) {
      LOG.debug("background fs {}|({})", name, handle);
    } else {
      BgTaskUtil.register(name, handle);
    }
    discoverNodesUrl = getConf(conf, "discover-nodes-url", null);
    homeDirPrefix = conf.get("dfs.user.home.dir.prefix", "/user");
    this.workingDir = getHomeDirectory();

    // hadoop29 and above check
    try {
      Class.forName("org.apache.hadoop.fs.StreamCapabilities");
      withStreamCapability = true;
    } catch (ClassNotFoundException e) {
      withStreamCapability = false;
    }
    if (withStreamCapability) {

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Check the client logs immediately before the exception: jfs_init logs the underlying native error.
  2. Verify juicefs.meta is reachable from the node: run 'juicefs status <meta-url>' with the same name/meta.
  3. Confirm object-storage credentials (access-key/secret-key or IAM) are valid and the bucket exists.
  4. Confirm the volume name was created via 'juicefs format' and matches juicefs.name.
  5. Test with the CLI on the same host: 'juicefs mount <meta> /tmp/jfs' to isolate Hadoop-specific config.

Example fix

// before
<property><name>juicefs.meta</name><value>redis://wrong-host:6379/1</value></property>
// after
<property><name>juicefs.meta</name><value>redis://redis-host:6379/1</value></property>
Defensive patterns

Strategy: try-catch

Validate before calling

// before mounting, validate metadata reachability from the shell:
// juicefs status <meta-url>  (must exit 0 and print the volume)
Process p = new ProcessBuilder("juicefs", "status", metaUrl).start();
if (p.waitFor() != 0) throw new IllegalStateException("meta unreachable: " + metaUrl);

Try / catch

try { fs = FileSystem.get(uri, conf); } catch (IOException e) { if (e.getMessage().startsWith("JuiceFS initialized failed")) { LOG.error("check juicefs.meta/credentials; native log above has details", e); } throw e; }

Prevention

When it happens

Trigger: jfs_init returns a non-positive handle during JuiceFileSystemImpl.initialize(); caused by an invalid juicefs.meta URL, unreachable/incorrect metadata engine, wrong object-storage credentials, or a volume name that does not exist.

Common situations: Metadata engine (Redis/MySQL) down or credentials wrong; object storage keys misconfigured; juicefs.name points to a volume never formatted; network egress from the Hadoop node blocked; wrong subdir setting.

Related errors

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