apache/hadoop · warning · IllegalArgumentException

Invalid DFS directory name ${result}

Error message

Invalid DFS directory name ${result}

What it means

WebHdfsFileSystem.setWorkingDirectory makes the supplied Path absolute and then validates its URI path with DFSUtilClient.isValidName. HDFS rejects non-canonical namespace names, including components containing ':', '.', or '..' and interior empty components. An invalid name is rejected immediately with IllegalArgumentException before workingDir is changed.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/WebHdfsFileSystem.java:472

        LOG.error("Unable to get HomeDirectory from original File System", e);
        cachedHomeDirectory = new Path("/user/" + ugi.getShortUserName())
            .makeQualified(this.getUri(), null);
      }
    }
    return cachedHomeDirectory;
  }

  @Override
  public synchronized Path getWorkingDirectory() {
    return workingDir;
  }

  @Override
  public synchronized void setWorkingDirectory(final Path dir) {
    Path absolutePath = makeAbsolute(dir);
    String result = absolutePath.toUri().getPath();
    if (!DFSUtilClient.isValidName(result)) {
      throw new IllegalArgumentException("Invalid DFS directory name " +
          result);
    }
    workingDir = absolutePath;
  }

  private Path makeAbsolute(Path f) {
    return f.isAbsolute()? f: new Path(workingDir, f);
  }

  @VisibleForTesting
  public static Map<?, ?> jsonParse(final HttpURLConnection c,
      final boolean useErrorStream) throws IOException {
    if (c.getContentLength() == 0) {
      return null;
    }
    final InputStream in = useErrorStream ?
        c.getErrorStream() : c.getInputStream();
    if (in == null) {

View on GitHub (pinned to 2add963021)

Solutions

1. Set a clean absolute directory such as new Path("/user/alice/jobs") with no ':' or dot components in any segment.
2. Validate the resolved absolute URI path with DFSUtilClient.isValidName before assigning it as the working directory.
3. Sanitize externally supplied directory names instead of embedding raw host:port, URL, or user input values.
4. Remember relative directories are resolved against the current working directory, so validate the final resolved path rather than the input string alone.

Example fix

// before
fs.setWorkingDirectory(new Path("/jobs/dn1:9866"));

// after
String raw = "/jobs/dn1_9866";
Path dir = new Path(raw);
if (!DFSUtilClient.isValidName(dir.toUri().getPath())) {
  throw new IllegalArgumentException("Invalid HDFS working directory: " + raw);
}
fs.setWorkingDirectory(dir);

Path absolute = dir.isAbsolute() ? dir : new Path(fs.getWorkingDirectory(), dir);
String name = absolute.toUri().getPath();
if (!DFSUtilClient.isValidName(name)) {
  throw new IllegalArgumentException("Invalid HDFS working directory name: " + name);
}
fs.setWorkingDirectory(absolute);

try {
  fs.setWorkingDirectory(dir);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Working directory must be an absolute, canonical HDFS path without ':' or dot components: " + dir, e);
}

When it happens

Trigger: Calling setWorkingDirectory with an absolute path such as /jobs/a:b, or a relative path that resolves against the current working directory to a name containing ':' or an unresolvable '..' component. The resulting path is passed to Path.toUri().getPath(), so scheme/authority are removed and the remaining namespace string must satisfy HDFS naming rules.

Common situations: Using a URL fragment or host:port string as a directory name; passing untrusted configuration paths into setWorkingDirectory; assuming HDFS accepts '.' or '..' components after URI normalization; porting code from a local file system where colons are allowed.

Related errors

• File does not exist: ${f}
• Parameter [{0}], invalid value [{1}], value must be [{2}]
• Wrong scheme: %s, in path: %s, expected scheme: %s
• Wrong bucket: %s, in path: %s, expected bucket: %s
• Wrong key length. Required ${options.getBitLength()}, but go

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