apache/hadoop · error · IOException

Invalid path string ${pathString}

Error message

Invalid path string ${pathString}

What it means

PathData.checkIfSchemeInferredFromPath (PathData.java:128) validates Windows paths during PathData construction (only when Path.WINDOWS is true). If a path matches windowsNonUriAbsolutePath1 — a backslash-separated drive-absolute path like C:\data — but also contains a forward slash anywhere, it throws IOException('Invalid path string <path>'). Mixing separators makes the path ambiguous, so Hadoop refuses it rather than guess.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/PathData.java:128

   */
  private PathData(FileSystem fs, String pathString) throws IOException {
    this(fs, pathString, lookupStat(fs, pathString, true));
  }

  /**
   * Validates the given Windows path.
   * @param pathString a String of the path supplied by the user.
   * @return true if the URI scheme was not present in the pathString but
   * inferred; false, otherwise.
   * @throws IOException if anything goes wrong
   */
  private static boolean checkIfSchemeInferredFromPath(String pathString)
  throws IOException
  {
    if (windowsNonUriAbsolutePath1.matcher(pathString).find()) {
      // Forward slashes disallowed in a backslash-separated path.
      if (pathString.indexOf('/') != -1) {
        throw new IOException("Invalid path string " + pathString);
      }

      return true;
    }

    // Is it a forward slash-separated absolute path?
    if (windowsNonUriAbsolutePath2.matcher(pathString).find()) {
      return true;
    }

    // Does it look like a URI? If so then just leave it alone.
    if (potentialUri.matcher(pathString).find()) {
      return false;
    }

    // Looks like a relative path on Windows.
    return false;
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Use one separator style consistently: 'C:\hadoop\tmp\file' or 'C:/hadoop/tmp/file' (forward-slash style also matches windowsNonUriAbsolutePath2 and is accepted)
2. Normalize before invoking: new Path(pathString.replace('\\', '/')) or build paths with org.apache.hadoop.fs.Path APIs
3. Pass a proper URI ('file:///C:/hadoop/tmp/file') to bypass Windows path inference entirely

Example fix

# before
hadoop fs -put C:\data\raw/file.log /ingest
# put: Invalid path string C:\data\raw/file.log

# after
hadoop fs -put file:///C:/data/raw/file.log /ingest

// normalize separators before constructing paths on Windows
String p = raw.replace('\\', '/');
PathData pd = new PathData(new Path(p), conf);

catch (IOException e) when message starts with 'Invalid path string' -> normalize the string (single separator style or file: URI) and re-construct

When it happens

Trigger: Constructing a PathData (any hadoop fs shell command resolving arguments) on Windows with an argument like 'C:\hadoop\tmp/file' or 'D:\data/logs'. Triggered from the private PathData(FileSystem, String, FileStatus) constructor's Path.WINDOWS branch.

Common situations: Windows clients running shell commands with paths assembled from mixed sources (Java File paths joined with '/' constants); scripts written on Cygwin/WSL interop passing mangled paths; config or code using File.separator mixed with hardcoded '/'.

Related errors

• Invalid path string
• {}
• Cannot create a file whose name looks like a directory: '%s'
• A file cannot be created in root.
• Rename to subdir is forbidden

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