{"record":{"id":"1353f6df5ef3c972","repo":"apache/hadoop","slug":"not-a-local-path","errorCode":null,"errorMessage":"Not a local path: ","messagePattern":"Not a local path: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/PathData.java","lineNumber":496,"sourceCode":"      }\n      return decodedRemainder;\n    } else {\n      StringBuilder buffer = new StringBuilder();\n      buffer.append(scheme)\n          .append(\":\")\n          .append(decodedRemainder);\n      return buffer.toString();\n    }\n  }\n  \n  /**\n   * Get the path to a local file\n   * @return File representing the local path\n   * @throws IllegalArgumentException if this.fs is not the LocalFileSystem\n   */\n  public File toFile() {\n    if (!(fs instanceof LocalFileSystem)) {\n       throw new IllegalArgumentException(\"Not a local path: \" + path);\n    }\n    return ((LocalFileSystem)fs).pathToFile(path);\n  }\n\n  /** Normalize the given Windows path string. This does the following:\n   *    1. Adds \"file:\" scheme for absolute paths.\n   *    2. Ensures the scheme-specific part starts with '/' per RFC2396.\n   *    3. Replaces backslash path separators with forward slashes.\n   *    @param pathString Path string supplied by the user.\n   *    @return normalized absolute path string. Returns the input string\n   *            if it is not a Windows absolute path.\n   */\n  private static String normalizeWindowsPath(String pathString)\n  throws IOException\n  {\n    if (!Path.WINDOWS) {\n      return pathString;\n    }","sourceCodeStart":478,"sourceCodeEnd":514,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/PathData.java#L478-L514","documentation":"PathData.toFile() (PathData.java:496) returns a java.io.File for the wrapped path, but only if the PathData's FileSystem is a LocalFileSystem; otherwise it throws IllegalArgumentException('Not a local path: <path>'). It exists because shell commands like get/copyToLocal must obtain a local File handle from a PathData, and an HDFS (or S3A, etc.) FileSystem has no local File representation.","triggerScenarios":"Calling toFile() (directly or via shell code paths such as CopyCommands' local-side IO that calls source.toFile().toPath()) on a PathData whose fs resolved to a non-local scheme: hdfs://, s3a://, viewfs across clusters. Typical trigger: the 'local' argument of a command accidentally resolving against the default (HDFS) filesystem because it lacked a file:// scheme or the fs.defaultFS is HDFS.","commonSituations":"Running commands where the local side is given as a bare absolute path '/tmp/file' while fs.defaultFS is hdfs://... so it resolves to HDFS, not the local FS; code that holds a PathData for a remote path and calls toFile(); custom FsCommand subclasses reusing toFile for convenience.","solutions":["Qualify the local side with the file: scheme: 'hadoop fs -get /hdfs/path file:///tmp/local/path' (or a relative path, which resolves locally)","In code, construct the local PathData against the local filesystem: new PathData(new Path('file:///tmp/f'), conf) or FileSystem.getLocal(conf)","Before calling toFile(), branch on 'pd.fs instanceof LocalFileSystem' and handle the remote case separately (copy via IOUtils)"],"exampleFix":"// before\nFile f = pathData.toFile(); // fs is hdfs -> IllegalArgumentException\n\n// after\nif (pathData.fs instanceof LocalFileSystem) {\n  File f = pathData.toFile();\n} else {\n  Path tmp = new Path('file:///tmp/staging', pathData.path.getName());\n  pathData.fs.copyToLocalFile(pathData.path, tmp);\n  File f = new File(tmp.toUri().getPath());\n}","handlingStrategy":"type-guard","validationCode":"if (!(pd.fs instanceof LocalFileSystem)) {\n  Path local = new Path(\"file:///tmp/staging\", pd.path.getName());\n  pd.fs.copyToLocalFile(pd.path, local);\n  // proceed with local.toUri().getPath()\n}","typeGuard":"boolean isLocalPathData(PathData pd) {\n  return pd.fs instanceof LocalFileSystem;\n}","tryCatchPattern":"catch (IllegalArgumentException e) when 'Not a local path' -> qualify the path with file:/// (or make it relative) so it resolves on the local filesystem, then retry","preventionTips":["Always prefix local paths with file:/// when fs.defaultFS is remote","Relative paths resolve locally; absolute bare paths may not","Construct local PathData via FileSystem.getLocal(conf)"],"tags":["not-a-local-path","local-filesystem","illegal-argument","pathdata"],"backgroundTag":"wrong-filesystem-scheme","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}