{"record":{"id":"0de8e34c29d900af","repo":"apache/hadoop","slug":"wrong-filesystem-stat-getpath","errorCode":null,"errorMessage":"Wrong FileSystem: \" + stat.getPath()","messagePattern":"Wrong FileSystem: \" \\+ stat\\.getPath\\(\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java","lineNumber":1237,"sourceCode":"    } catch (NoSuchFileException e) {\n      throw new FileNotFoundException(\"File \" + p + \" does not exist\");\n    }\n  }\n\n  /**\n   * Hook to implement support for {@link PathHandle} operations.\n   * @param stat Referent in the target FileSystem\n   * @param opts Constraints that determine the validity of the\n   *            {@link PathHandle} reference.\n   */\n  protected PathHandle createPathHandle(FileStatus stat,\n      Options.HandleOpt... opts) {\n    if (stat.isDirectory() || stat.isSymlink()) {\n      throw new IllegalArgumentException(\"PathHandle only available for files\");\n    }\n    String authority = stat.getPath().toUri().getAuthority();\n    if (authority != null && !authority.equals(\"file://\")) {\n      throw new IllegalArgumentException(\"Wrong FileSystem: \" + stat.getPath());\n    }\n    Options.HandleOpt.Data data =\n        Options.HandleOpt.getOpt(Options.HandleOpt.Data.class, opts)\n            .orElse(Options.HandleOpt.changed(false));\n    Options.HandleOpt.Location loc =\n        Options.HandleOpt.getOpt(Options.HandleOpt.Location.class, opts)\n            .orElse(Options.HandleOpt.moved(false));\n    if (loc.allowChange()) {\n      throw new UnsupportedOperationException(\"Tracking file movement in \" +\n          \"basic FileSystem is not supported\");\n    }\n    final Path p = stat.getPath();\n    final Optional<Long> mtime = !data.allowChange()\n        ? Optional.of(stat.getModificationTime())\n        : Optional.empty();\n    return new LocalFileSystemPathHandle(p.toString(), mtime);\n  }\n","sourceCodeStart":1219,"sourceCodeEnd":1255,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java#L1219-L1255","documentation":"Thrown by RawLocalFileSystem.createPathHandle when the FileStatus passed in carries a path whose URI authority does not match the local FileSystem. The local implementation only accepts paths with a null authority (a plain file:/// path has null authority, so any non-null authority other than the literal \"file://\" comparison fails). It is the library's guard against mixing a FileStatus produced by one FileSystem with the handle factory of another.","triggerScenarios":"Getting FileStatus from one FileSystem (e.g. hdfs.getFileStatus(new Path(\"hdfs://nn/user/a/f\"))) and passing it to another's getPathHandle (e.g. localFs.getPathHandle(stat)). Any qualified path like file://localhost/... or hdfs://nameservice/... yields a non-null authority and triggers the throw.","commonSituations":"Utility code that caches a single FileSystem instance while handling paths from multiple schemes; refactoring that changed the default FS in core-site.xml; code that receives FileStatus objects over RPC and assumes they are local.","solutions":["Call getPathHandle on the FileSystem that owns the path: stat.getPath().getFileSystem(conf).getPathHandle(stat)","Re-fetch the status locally before creating the handle: localFs.getFileStatus(localFs.makeQualified(p))","Verify the scheme/authority of stat.getPath() matches fs.getUri() before calling getPathHandle"],"exampleFix":"// before\nFileStatus st = hdfs.getFileStatus(new Path(\"hdfs://nn/user/a/f\"));\nPathHandle h = localFs.getPathHandle(st); // Wrong FileSystem\n\n// after\nPathHandle h = hdfs.getPathHandle(st);   // ask the FS that produced the status","handlingStrategy":"validation","validationCode":"URI u = stat.getPath().toUri();\nFileSystem owner;\ntry {\n  owner = stat.getPath().getFileSystem(conf);\n} catch (IOException e) {\n  throw new IllegalArgumentException(\"Unresolvable path \" + stat.getPath(), e);\n}\nif (!owner.getUri().relativize(owner.makeQualified(stat.getPath()).toUri()).isAbsolute()\n    && !owner.equals(fs)) {\n  fs = owner; // ask the owning FileSystem for the handle\n}\nPathHandle h = fs.getPathHandle(stat);","typeGuard":null,"tryCatchPattern":"try {\n  PathHandle h = fs.getPathHandle(stat);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Wrong FileSystem\")) {\n    // status and filesystem disagree; re-fetch from the right FS\n  }\n}","preventionTips":["Create handles only on the FileSystem instance that produced the FileStatus","Keep FileStatus objects paired with their source FileSystem in data structures instead of passing them bare"],"tags":["hadoop","local-filesystem","pathhandle","uri-mismatch"],"backgroundTag":"filesystem-scheme-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}