apache/hadoop · error · InvalidPathHandleException

Wrong file

Error message

Wrong file

What it means

HdfsPathHandle.verify(stat) throws InvalidPathHandleException('Wrong file') when the inodeId embedded in the handle differs from the resolved file's inodeId. Same path but different inode means the file was deleted and re-created (new inode), so the handle's identity no longer matches even if mtime coincidentally does.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/protocol/HdfsPathHandle.java:76

    path = p.getPath();
    mtime   = p.hasMtime()   ? p.getMtime()   : null;
    inodeId = p.hasInodeId() ? p.getInodeId() : null;
  }

  public String getPath() {
    return path;
  }

  public void verify(HdfsLocatedFileStatus stat)
      throws InvalidPathHandleException {
    if (null == stat) {
      throw new InvalidPathHandleException("Could not resolve handle");
    }
    if (mtime != null && mtime != stat.getModificationTime()) {
      throw new InvalidPathHandleException("Content changed");
    }
    if (inodeId != null && inodeId != stat.getFileId()) {
      throw new InvalidPathHandleException("Wrong file");
    }
  }

  @Override
  public ByteBuffer bytes() {
    HdfsPathHandleProto.Builder b = HdfsPathHandleProto.newBuilder();
    b.setPath(path);
    if (inodeId != null) {
      b.setInodeId(inodeId);
    }
    if (mtime != null) {
      b.setMtime(mtime);
    }
    return b.build().toByteString().asReadOnlyByteBuffer();
  }

  @Override
  public boolean equals(Object other) {

View on GitHub (pinned to 2add963021)

Solutions

1. Treat the handle as invalid: re-resolve the path and mint a new PathHandle.
2. Design writers to create new paths (or use append) rather than delete+recreate files that others hold handles to.
3. Persist the source generation id along with the handle so consumers can detect lineage resets.

// Verify inode identity before opening via handle
HdfsLocatedFileStatus st = (HdfsLocatedFileStatus) fs.getFileStatus(new Path(handle.getPath()));
// if st.getFileId() != your recorded inodeId, the file was replaced — re-mint the handle

try (FSDataInputStream in = fs.open(handle)) {
  ...
} catch (InvalidPathHandleException e) {
  if (e.getMessage().contains("Wrong file")) {
    // inode replaced at same path — regenerate the handle from the current file
  }
}

When it happens

Trigger: open(PathHandle) after the target file was removed and recreated at the same path (common with atomic 'write temp + rename' pipelines that replace output), or after truncate-like operations that cycle inodes.

Common situations: Job dedup workflows that delete-then-rewrite output; snapshot restore that recreates inodes; handles persisted across such operations.

Related errors

• Could not resolve handle
• INode XML found with no <type> tag.
• <inode> found without <id>
• Content changed
• ${className} does not support positioned read.

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