apache/hadoop · error · InvalidPathHandleException

Content changed

Error message

Content changed

What it means

HdfsPathHandle.verify(stat) throws InvalidPathHandleException('Content changed') when the modification time recorded in the handle differs from the current file's mtime. The handle pins content identity via mtime (and optionally inodeId); an mtime mismatch means the file was written or touched after the handle was created.

Source

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

    }
    HdfsPathHandleProto p =
        HdfsPathHandleProto.parseFrom(ByteString.copyFrom(bytes));
    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();
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Write to a new path per generation and hand out fresh handles instead of mutating files referenced by handles.
2. If the change is expected (benign touch), rebuild the handle from the current status.
3. Use Option.IO.BYTE_RANGE reads and verify content checksums if partial staleness matters.

// Detect mtime drift before opening via handle
HdfsLocatedFileStatus st = (HdfsLocatedFileStatus) fs.getFileStatus(new Path(handle.getPath()));
// compare st.getModificationTime() against your recorded mtime; if different, re-mint the handle

try (FSDataInputStream in = fs.open(handle)) {
  ...
} catch (InvalidPathHandleException e) {
  if (e.getMessage().contains("Content changed")) {
    // file was modified since handle creation — revalidate or regenerate
  }
}

When it happens

Trigger: FileSystem.open(PathHandle) after the file was appended to, overwritten, or even merely touched (e.g. setTimes, some rename/chown operations updating mtime) between handle creation and open.

Common situations: MapReduce/Spark pipelines where a later stage rewrites output in place; tooling that normalizes timestamps after copying; two writers racing on the same path.

Related errors

• Content changed
• Could not resolve handle
• Wrong file
• ${className} does not support positioned read.
• ${className} does not support positioned reads with byte buf

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