{"record":{"id":"c690a645cf1ce5b3","repo":"juicedata/juicefs","slug":"juicefs-initialized-failed-for-jfs-name","errorCode":null,"errorMessage":"JuiceFS initialized failed for jfs://\" + name","messagePattern":"JuiceFS initialized failed for jfs://\" \\+ name","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java","lineNumber":517,"sourceCode":"    obj.put(\"readahead\", getConf(conf, \"max-readahead\", \"0\"));\n    obj.put(\"pushGateway\", getConf(conf, \"push-gateway\", \"\"));\n    obj.put(\"pushInterval\", getConf(conf, \"push-interval\", \"10\"));\n    obj.put(\"pushAuth\", getConf(conf, \"push-auth\", \"\"));\n    obj.put(\"pushLabels\", getConf(conf, \"push-labels\", \"\"));\n    obj.put(\"pushGraphite\", getConf(conf, \"push-graphite\", \"\"));\n    obj.put(\"pushRemoteWrite\", getConf(conf, \"push-remote-write\", \"\"));\n    obj.put(\"pushRemoteWriteAuth\", getConf(conf, \"push-remote-write-auth\", \"\"));\n    obj.put(\"guidMask\", getConf(conf, \"guid-mask\", \"\"));\n    obj.put(\"fastResolve\", Boolean.valueOf(getConf(conf, \"fast-resolve\", \"true\")));\n    obj.put(\"noUsageReport\", Boolean.valueOf(getConf(conf, \"no-usage-report\", \"false\")));\n    obj.put(\"freeSpace\", getConf(conf, \"free-space\", \"0.1\"));\n    obj.put(\"accessLog\", getConf(conf, \"access-log\", \"\"));\n    obj.put(\"superFs\", asSuperFs);\n    obj.put(\"subdir\", subdir);\n    String jsonConf = obj.toString(2);\n    handle = lib.jfs_init(credential, crdSize, name, jsonConf, user, groupStr, superuser, supergroup);\n    if (handle <= 0) {\n      throw new IOException(\"JuiceFS initialized failed for jfs://\" + name);\n    }\n    if (isBackGroundTask) {\n      LOG.debug(\"background fs {}|({})\", name, handle);\n    } else {\n      BgTaskUtil.register(name, handle);\n    }\n    discoverNodesUrl = getConf(conf, \"discover-nodes-url\", null);\n    homeDirPrefix = conf.get(\"dfs.user.home.dir.prefix\", \"/user\");\n    this.workingDir = getHomeDirectory();\n\n    // hadoop29 and above check\n    try {\n      Class.forName(\"org.apache.hadoop.fs.StreamCapabilities\");\n      withStreamCapability = true;\n    } catch (ClassNotFoundException e) {\n      withStreamCapability = false;\n    }\n    if (withStreamCapability) {","sourceCodeStart":499,"sourceCodeEnd":535,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java#L499-L535","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the client logs immediately before the exception: jfs_init logs the underlying native error.","Verify juicefs.meta is reachable from the node: run 'juicefs status <meta-url>' with the same name/meta.","Confirm object-storage credentials (access-key/secret-key or IAM) are valid and the bucket exists.","Confirm the volume name was created via 'juicefs format' and matches juicefs.name.","Test with the CLI on the same host: 'juicefs mount <meta> /tmp/jfs' to isolate Hadoop-specific config."],"exampleFix":"// before\n<property><name>juicefs.meta</name><value>redis://wrong-host:6379/1</value></property>\n// after\n<property><name>juicefs.meta</name><value>redis://redis-host:6379/1</value></property>","handlingStrategy":"try-catch","validationCode":"// before mounting, validate metadata reachability from the shell:\n// juicefs status <meta-url>  (must exit 0 and print the volume)\nProcess p = new ProcessBuilder(\"juicefs\", \"status\", metaUrl).start();\nif (p.waitFor() != 0) throw new IllegalStateException(\"meta unreachable: \" + metaUrl);","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Run 'juicefs status <meta>' from every worker node before rollout.","Validate object-storage credentials with 'juicefs gc' or a small mount test.","Keep juicefs.name and juicefs.meta consistent across nodes.","Monitor metadata engine availability."],"tags":["native-library","initialization","configuration"],"backgroundTag":"module-init-failed","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}