juicedata/juicefs · error · IOException

name is required

Error message

name is required

What it means

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.

Source

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

  private String getConf(Configuration conf, String key, String value) {
    String v = conf.get("juicefs." + key, value);
    if (name != null && !name.equals("")) {
      v = conf.get("juicefs." + name + "." + key, v);
    }
    if (v != null)
      v = v.trim();
    return v;
  }

  @Override
  public void initialize(URI uri, Configuration conf) throws IOException {
    super.initialize(uri, conf);
    setConf(conf);

    this.uri = uri;
    name = conf.get("juicefs.name", uri.getHost());
    if (null == name) {
      throw new IOException("name is required");
    }

    blocksize = conf.getLongBytes("juicefs.block.size", conf.getLongBytes("dfs.blocksize", 128 << 20));
    minBufferSize = conf.getInt("juicefs.min-buffer-size", 128 << 10);
    cacheReplica = Integer.parseInt(getConf(conf, "cache-replica", "1"));
    fileChecksumEnabled = Boolean.parseBoolean(getConf(conf, "file.checksum", "false"));

    this.ugi = UserGroupInformation.getCurrentUser();
    user = ugi.getShortUserName();
    String groupStr = "nogroup";
    if (ugi.getGroupNames().length > 0) {
      groupStr = String.join(",", ugi.getGroupNames());
    }
    superuser = getConf(conf, "superuser", "hdfs");
    supergroup = getConf(conf, "supergroup", conf.get("dfs.permissions.superusergroup", "supergroup"));
    isBackGroundTask = conf.getBoolean("juicefs.internal-bg-task", false);
    boolean asSuperFs = isSuperGroupFileSystem || isBackGroundTask;

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Set the volume name in the Hadoop configuration: conf.set("juicefs.name", "myvol").
2. Use a URI that carries the name as the host: jfs://myvol/path.
3. Verify core-site.xml (or the job's Configuration) actually contains juicefs.name and is on the classpath.
4. If using a symlinked/aliased name, ensure juicefs.meta points to the correct metadata URL for that name.

Example fix

// before
FileSystem.get(URI.create("jfs:///data"), conf); // throws: no host, no juicefs.name
// after
conf.set("juicefs.name", "myvol");
FileSystem.get(URI.create("jfs:///data"), conf);

Configuration conf = ...;
String name = conf.get("juicefs.name", uri.getHost());
if (name == null || name.isEmpty()) {
  throw new IllegalArgumentException("Set juicefs.name or use jfs://<name>/... URI");
}

try { fs = FileSystem.get(uri, conf); } catch (IOException e) { if (e.getMessage().contains("name is required")) { /* fix config and retry */ } else throw e; }

When it happens

Trigger: Calling FileSystem.get() or initialize() with a URI like jfs:///path (empty host) while 'juicefs.name' is not set in the Hadoop Configuration.

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

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Could not get a FileSystem
• Cannot load default config
• Cannot get file system.
• Cannot create file system.
• renew token failed

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