apache/hadoop · error · IllegalArgumentException

Invalid DFS directory name

Error message

Invalid DFS directory name 

What it means

Error "Invalid DFS directory name " thrown in apache/hadoop.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java:232

  public Path getWorkingDirectory() {
    return workingDir;
  }

  @Override
  public long getDefaultBlockSize() {
    return dfs.getConf().getDefaultBlockSize();
  }

  @Override
  public short getDefaultReplication() {
    return dfs.getConf().getDefaultReplication();
  }

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

  @Override
  public Path getHomeDirectory() {
    return makeQualified(
        new Path(DFSUtilClient.getHomeDirectory(getConf(), dfs.ugi)));
  }

  /**
   * Returns the hedged read metrics object for this client.
   *
   * @return object of DFSHedgedReadMetrics
   */
  public DFSHedgedReadMetrics getHedgedReadMetrics() {
    return dfs.getHedgedReadMetrics();

View on GitHub (pinned to 2add963021)

Solutions

1. Pass a valid absolute DFS path (starting with /) and without illegal characters.
2. Verify the path string before calling the FileSystem API; normalize or strip whitespace.

When it happens

Trigger: An operation receives a path string that is not a valid DFS directory name (for example malformed or empty), and it is rejected before any NameNode call.

Common situations: See trigger scenarios.

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