{"record":{"id":"1fbe28183685cf4f","repo":"juicedata/juicefs","slug":"name-is-required","errorCode":null,"errorMessage":"name is required","messagePattern":"name is required","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java","lineNumber":388,"sourceCode":"  private String getConf(Configuration conf, String key, String value) {\n    String v = conf.get(\"juicefs.\" + key, value);\n    if (name != null && !name.equals(\"\")) {\n      v = conf.get(\"juicefs.\" + name + \".\" + key, v);\n    }\n    if (v != null)\n      v = v.trim();\n    return v;\n  }\n\n  @Override\n  public void initialize(URI uri, Configuration conf) throws IOException {\n    super.initialize(uri, conf);\n    setConf(conf);\n\n    this.uri = uri;\n    name = conf.get(\"juicefs.name\", uri.getHost());\n    if (null == name) {\n      throw new IOException(\"name is required\");\n    }\n\n    blocksize = conf.getLongBytes(\"juicefs.block.size\", conf.getLongBytes(\"dfs.blocksize\", 128 << 20));\n    minBufferSize = conf.getInt(\"juicefs.min-buffer-size\", 128 << 10);\n    cacheReplica = Integer.parseInt(getConf(conf, \"cache-replica\", \"1\"));\n    fileChecksumEnabled = Boolean.parseBoolean(getConf(conf, \"file.checksum\", \"false\"));\n\n    this.ugi = UserGroupInformation.getCurrentUser();\n    user = ugi.getShortUserName();\n    String groupStr = \"nogroup\";\n    if (ugi.getGroupNames().length > 0) {\n      groupStr = String.join(\",\", ugi.getGroupNames());\n    }\n    superuser = getConf(conf, \"superuser\", \"hdfs\");\n    supergroup = getConf(conf, \"supergroup\", conf.get(\"dfs.permissions.superusergroup\", \"supergroup\"));\n    isBackGroundTask = conf.getBoolean(\"juicefs.internal-bg-task\", false);\n    boolean asSuperFs = isSuperGroupFileSystem || isBackGroundTask;\n","sourceCodeStart":370,"sourceCodeEnd":406,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/sdk/java/src/main/java/io/juicefs/JuiceFileSystemImpl.java#L370-L406","documentation":"JuiceFileSystemImpl.initialize() resolves the volume name from the config key 'juicefs.name' or, if unset, from the URI host. If both are absent, the filesystem cannot identify which JuiceFS volume to attach to, so it throws this IOException before any native initialization happens.","triggerScenarios":"Calling FileSystem.get() or initialize() with a URI like jfs:///path (empty host) while 'juicefs.name' is not set in the Hadoop Configuration.","commonSituations":"Mounting via a core-site.xml fs.defaultFS of jfs:/// without juicefs.name; programmatic Configuration built without the juicefs.name property; copying a config template that omitted the volume name set during 'juicefs format'.","solutions":["Set the volume name in the Hadoop configuration: conf.set(\"juicefs.name\", \"myvol\").","Use a URI that carries the name as the host: jfs://myvol/path.","Verify core-site.xml (or the job's Configuration) actually contains juicefs.name and is on the classpath.","If using a symlinked/aliased name, ensure juicefs.meta points to the correct metadata URL for that name."],"exampleFix":"// before\nFileSystem.get(URI.create(\"jfs:///data\"), conf); // throws: no host, no juicefs.name\n// after\nconf.set(\"juicefs.name\", \"myvol\");\nFileSystem.get(URI.create(\"jfs:///data\"), conf);","handlingStrategy":"validation","validationCode":"Configuration conf = ...;\nString name = conf.get(\"juicefs.name\", uri.getHost());\nif (name == null || name.isEmpty()) {\n  throw new IllegalArgumentException(\"Set juicefs.name or use jfs://<name>/... URI\");\n}","typeGuard":null,"tryCatchPattern":"try { fs = FileSystem.get(uri, conf); } catch (IOException e) { if (e.getMessage().contains(\"name is required\")) { /* fix config and retry */ } else throw e; }","preventionTips":["Always set juicefs.name in core-site.xml or job Configuration.","Prefer URIs with the volume as host: jfs://myvol/path.","Add a startup check that logs the resolved volume name before mounting.","Keep volume-name conventions documented for the team."],"tags":["hadoop","filesystem","configuration"],"backgroundTag":"missing-required-config","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}