apache/hadoop · error · InvalidPathException

Path part {s} from URI {p} is not a valid filename.

Error message

Path part {s} from URI {p} is not a valid filename.

What it means

AbstractFileSystem.getUriPath calls checkPath and then validates the URI path part with isValidName, whose default rules (AbstractFileSystem.java:111) reject any path component equal to ".." or "." or containing a colon ':'. Hadoop Path normalization keeps ".." components, so unnormalized parents and colon-bearing filenames surface here as InvalidPathException.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/AbstractFileSystem.java:427

          + ", expected: "
          + this.getUri()
          + " with port=" + thisPort);
    }
  }
  
  /**
   * Get the path-part of a pathname. Checks that URI matches this file system
   * and that the path-part is a valid name.
   * 
   * @param p path
   * 
   * @return path-part of the Path p
   */
  public String getUriPath(final Path p) {
    checkPath(p);
    String s = p.toUri().getPath();
    if (!isValidName(s)) {
      throw new InvalidPathException("Path part " + s + " from URI " + p
          + " is not a valid filename.");
    }
    return s;
  }
  
  /**
   * Make the path fully qualified to this file system
   * @param path the path.
   * @return the qualified path
   */
  public Path makeQualified(Path path) {
    checkPath(path);
    return path.makeQualified(this.getUri(), null);
  }
  
  /**
   * Some file systems like LocalFileSystem have an initial workingDir
   * that is used as the starting workingDir. For other file systems

View on GitHub (pinned to 2add963021)

Solutions

1. Sanitize file name components: strip/replace ':' (e.g. '_' for '_' + timestamp with '-' separators)
2. Resolve ".." and "." components before the call (e.g. new Path(path.toUri().normalize()) or your own resolution), since Path will not do it for you
3. Pre-check with afs.isValidName(path.toUri().getPath()) and reject bad input early at the API boundary

Example fix

// before
String name = "log:" + Instant.now(); // colon in component
afs.getUriPath(new Path("/logs/" + name)); // Path part ... is not a valid filename

// after
String name = "log-" + Instant.now().toString().replace(':', '-');
afs.getUriPath(new Path("/logs/" + name));

String pathPart = p.toUri().getPath();
if (!afs.isValidName(pathPart)) {
  // resolve '..'/'.' and replace ':' in components before use
  pathPart = pathPart.replace(":", "_");
  p = new Path(p.toUri().getScheme(), p.toUri().getAuthority(), pathPart);
}

catch (InvalidPathException e) { if (e.getMessage().startsWith("Path part")) { /* sanitize the offending component and retry */ } else throw e; }

When it happens

Trigger: A path containing ".." segments (new Path("/a/../b") is kept as-is), a stray "." component, or a filename with ':' such as "backup:2024-01-01" or Windows-style "C:" fragments; any FileContext operation that ends in getUriPath on such a path.

Common situations: Filenames generated from timestamps containing colons; user-supplied file names not sanitized; porting Windows paths; symlink-heavy code where ".." is expected to resolve late; note file systems may override isValidName with different rules.

Related errors

• Wrong scheme: %s, in path: %s, expected scheme: %s
• Wrong bucket: %s, in path: %s, expected bucket: %s
• relative paths not allowed:{path}
• Path without scheme with non-null authority:{path}
• Path is relative

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