{"record":{"id":"24a96c70077813fa","repo":"apache/hadoop","slug":"invalid-path-string-pathstring","errorCode":null,"errorMessage":"Invalid path string ${pathString}","messagePattern":"Invalid path string (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/PathData.java","lineNumber":128,"sourceCode":"   */\n  private PathData(FileSystem fs, String pathString) throws IOException {\n    this(fs, pathString, lookupStat(fs, pathString, true));\n  }\n\n  /**\n   * Validates the given Windows path.\n   * @param pathString a String of the path supplied by the user.\n   * @return true if the URI scheme was not present in the pathString but\n   * inferred; false, otherwise.\n   * @throws IOException if anything goes wrong\n   */\n  private static boolean checkIfSchemeInferredFromPath(String pathString)\n  throws IOException\n  {\n    if (windowsNonUriAbsolutePath1.matcher(pathString).find()) {\n      // Forward slashes disallowed in a backslash-separated path.\n      if (pathString.indexOf('/') != -1) {\n        throw new IOException(\"Invalid path string \" + pathString);\n      }\n\n      return true;\n    }\n\n    // Is it a forward slash-separated absolute path?\n    if (windowsNonUriAbsolutePath2.matcher(pathString).find()) {\n      return true;\n    }\n\n    // Does it look like a URI? If so then just leave it alone.\n    if (potentialUri.matcher(pathString).find()) {\n      return false;\n    }\n\n    // Looks like a relative path on Windows.\n    return false;\n  }","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/PathData.java#L110-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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 '/'.","solutions":["Use one separator style consistently: 'C:\\hadoop\\tmp\\file' or 'C:/hadoop/tmp/file' (forward-slash style also matches windowsNonUriAbsolutePath2 and is accepted)","Normalize before invoking: new Path(pathString.replace('\\\\', '/')) or build paths with org.apache.hadoop.fs.Path APIs","Pass a proper URI ('file:///C:/hadoop/tmp/file') to bypass Windows path inference entirely"],"exampleFix":"# before\nhadoop fs -put C:\\data\\raw/file.log /ingest\n# put: Invalid path string C:\\data\\raw/file.log\n\n# after\nhadoop fs -put file:///C:/data/raw/file.log /ingest","handlingStrategy":"validation","validationCode":"// normalize separators before constructing paths on Windows\nString p = raw.replace('\\\\', '/');\nPathData pd = new PathData(new Path(p), conf);","typeGuard":null,"tryCatchPattern":"catch (IOException e) when message starts with 'Invalid path string' -> normalize the string (single separator style or file: URI) and re-construct","preventionTips":["Pick one separator style for all Windows paths (forward slashes recommended)","Build paths via Path/PathData APIs, not string concatenation","Prefer file:/// URIs for local paths on Windows"],"tags":["windows","path-validation","invalid-path","mixed-separators","pathdata"],"backgroundTag":"invalid-path-format","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}