apache/hadoop · error · IllegalArgumentException

Home dir should start with /:{homedir}

Error message

Home dir should start with /:{homedir}

What it means

ConfigUtil.setHomeDirConf writes fs.viewfs.mounttable.<name>.homedir into a Configuration for ViewFs. It enforces that the home dir starts with '/', because a ViewFs home must be an absolute path inside the mount-table namespace; otherwise IllegalArgumentException('Home dir should start with /:<homedir>') is thrown before the property is set.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/ConfigUtil.java:223

   * Add config variable for homedir for default mount table
   * @param conf - add to this conf
   * @param homedir - the home dir path starting with slash
   */
  public static void setHomeDirConf(final Configuration conf,
      final String homedir) {
    setHomeDirConf(conf, getDefaultMountTableName(conf), homedir);
  }
  
  /**
   * Add config variable for homedir the specified mount table
   * @param conf - add to this conf
   * @param homedir - the home dir path starting with slash
   * @param mountTableName - the mount table.
   */
  public static void setHomeDirConf(final Configuration conf,
              final String mountTableName, final String homedir) {
    if (!homedir.startsWith("/")) {
      throw new IllegalArgumentException("Home dir should start with /:"
          + homedir);
    }
    conf.set(getConfigViewFsPrefix(mountTableName) + "." +
        Constants.CONFIG_VIEWFS_HOMEDIR, homedir);
  }
  
  /**
   * Get the value of the home dir conf value for default mount table
   * @param conf - from this conf
   * @return home dir value, null if variable is not in conf
   */
  public static String getHomeDirValue(final Configuration conf) {
    return getHomeDirValue(conf, getDefaultMountTableName(conf));
  }
  
  /**
   * Get the value of the home dir conf value for specified mount table
   * @param conf - from this conf

View on GitHub (pinned to 2add963021)

Solutions

1. Pass an absolute path: '/user/alice'
2. Normalize before the call: homedir = homedir.startsWith('/') ? homedir : '/' + homedir
3. Derive per-user homes from a fixed '/user' base constant

Example fix

// before
ConfigUtil.setHomeDirConf(conf, mountTable, "user/" + user);

// after
ConfigUtil.setHomeDirConf(conf, mountTable, "/user/" + user);

static String absoluteHome(String homeDir) {
  if (!homeDir.startsWith("/")) {
    throw new IllegalArgumentException("Home dir must be absolute: " + homeDir);
  }
  return homeDir;
}
ConfigUtil.setHomeDirConf(conf, mountTable, absoluteHome(home));

Catch IllegalArgumentException from setHomeDirConf; the message shows the offending value, so fail config generation with the corrected absolute path.

When it happens

Trigger: Calling ConfigUtil.setHomeDirConf(conf, mountTable, 'user/alice') or setHomeDirDirConf(...) with a relative path; composing the home dir from a username without a base.

Common situations: Programmatic mount-table setup that concatenates 'user/' + name instead of '/user/' + name; home values read from properties that lack the leading slash.

Related errors

• ViewFs: Non absolute mount name in config:{src}
• Wrong FS {} -expected {}
• Path {nextInode.fullPath} already exists as link
• Path {strB} already exists as dir; cannot create link here
• Unexpected mount table link entry '{key}'. Use linkMergeSlas

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/12c3629b8315d5e6. Report an issue: GitHub.