apache/hadoop · error · InvalidPathHandleException

Content changed

Error message

Content changed

What it means

LocalFileSystemPathHandle optionally captures the file mtime; verify(FileStatus) throws InvalidPathHandleException("Content changed") when a stored mtime exists and differs from the file's current modification time — i.e. the file changed after the handle was created.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/LocalFileSystemPathHandle.java:59

    if (null == bytes) {
      throw new IOException("Missing PathHandle");
    }
    LocalFileSystemPathHandleProto p =
        LocalFileSystemPathHandleProto.parseFrom(ByteString.copyFrom(bytes));
    path = p.hasPath()   ? p.getPath()  : null;
    mtime = p.hasMtime() ? p.getMtime() : null;
  }

  public String getPath() {
    return path;
  }

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

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

  @Override
  public boolean equals(Object o) {
    if (this == o) {
      return true;

View on GitHub (pinned to 2add963021)

Solutions

1. Re-capture the handle after content stabilizes and republish it to consumers
2. Create handles without mtime when strict mtime checking is not wanted
3. Enforce single-writer discipline: write to temp, atomic rename, then publish handles

Example fix

// before
handle.verify(fs.getFileStatus(p));
// after
try { handle.verify(fs.getFileStatus(p)); }
catch (InvalidPathHandleException e) { /* content changed: re-acquire handle or reprocess file */ }

try {
  handle.verify(fs.getFileStatus(p));
} catch (InvalidPathHandleException e) {
  // 'Content changed': mtime differs — re-capture the handle or reprocess the file
}

When it happens

Trigger: Verifying a handle after the target file was overwritten, rewritten, truncated+rewritten, touched, or restored without preserving mtime.

Common situations: Concurrent writers finalizing in place, jobs regenerating intermediate files, rsync/tar restores not preserving mtimes, reprocessing pipelines assuming file immutability.

Related errors

• Content changed
• Missing PathHandle
• Could not resolve handle
• Block length mismatch, len={len} but r={r}
• Could not resolve handle

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