apache/hadoop · error · IllegalArgumentException

Wrong FileSystem: " + stat.getPath()

Error message

Wrong FileSystem: " + stat.getPath()

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java:1237

    } catch (NoSuchFileException e) {
      throw new FileNotFoundException("File " + p + " does not exist");
    }
  }

  /**
   * Hook to implement support for {@link PathHandle} operations.
   * @param stat Referent in the target FileSystem
   * @param opts Constraints that determine the validity of the
   *            {@link PathHandle} reference.
   */
  protected PathHandle createPathHandle(FileStatus stat,
      Options.HandleOpt... opts) {
    if (stat.isDirectory() || stat.isSymlink()) {
      throw new IllegalArgumentException("PathHandle only available for files");
    }
    String authority = stat.getPath().toUri().getAuthority();
    if (authority != null && !authority.equals("file://")) {
      throw new IllegalArgumentException("Wrong FileSystem: " + stat.getPath());
    }
    Options.HandleOpt.Data data =
        Options.HandleOpt.getOpt(Options.HandleOpt.Data.class, opts)
            .orElse(Options.HandleOpt.changed(false));
    Options.HandleOpt.Location loc =
        Options.HandleOpt.getOpt(Options.HandleOpt.Location.class, opts)
            .orElse(Options.HandleOpt.moved(false));
    if (loc.allowChange()) {
      throw new UnsupportedOperationException("Tracking file movement in " +
          "basic FileSystem is not supported");
    }
    final Path p = stat.getPath();
    final Optional<Long> mtime = !data.allowChange()
        ? Optional.of(stat.getModificationTime())
        : Optional.empty();
    return new LocalFileSystemPathHandle(p.toString(), mtime);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Call getPathHandle on the FileSystem that owns the path: stat.getPath().getFileSystem(conf).getPathHandle(stat)
2. Re-fetch the status locally before creating the handle: localFs.getFileStatus(localFs.makeQualified(p))
3. Verify the scheme/authority of stat.getPath() matches fs.getUri() before calling getPathHandle

Example fix

// before
FileStatus st = hdfs.getFileStatus(new Path("hdfs://nn/user/a/f"));
PathHandle h = localFs.getPathHandle(st); // Wrong FileSystem

// after
PathHandle h = hdfs.getPathHandle(st);   // ask the FS that produced the status

URI u = stat.getPath().toUri();
FileSystem owner;
try {
  owner = stat.getPath().getFileSystem(conf);
} catch (IOException e) {
  throw new IllegalArgumentException("Unresolvable path " + stat.getPath(), e);
}
if (!owner.getUri().relativize(owner.makeQualified(stat.getPath()).toUri()).isAbsolute()
    && !owner.equals(fs)) {
  fs = owner; // ask the owning FileSystem for the handle
}
PathHandle h = fs.getPathHandle(stat);

try {
  PathHandle h = fs.getPathHandle(stat);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Wrong FileSystem")) {
    // status and filesystem disagree; re-fetch from the right FS
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• PathHandle only available for files
• Tracking file movement in basic FileSystem is not supported
• Checksum file not a length multiple of checksum size in {} a
• Checksum error: {} at {}
• Checksum error: {} at {} exp: {} got: {}

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