What causes "Could not resolve handle" in apache/hadoop?

Resolve the status yourself (fs.getFileStatus) and handle FileNotFoundException before calling verify

apache/hadoop · error · InvalidPathHandleException

Could not resolve handle

Error message

Could not resolve handle

What it means

PathHandle.verify(FileStatus) checks a resolved file against the handle. verify(null) means nothing was resolved for the handle's path, and LocalFileSystemPathHandle rejects it with InvalidPathHandleException before any mtime comparison.

Source

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

  }

  public LocalFileSystemPathHandle(ByteBuffer bytes) throws IOException {
    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

View on GitHub (pinned to 2add963021)

Solutions

Resolve the status yourself (fs.getFileStatus) and handle FileNotFoundException before calling verify
Never pass null into verify; treat an unresolvable path via the getFileStatus exception path
Fix wrappers to throw FileNotFoundException rather than return null

Example fix

// before
handle.verify(stat);                        // stat == null
// after
FileStatus stat = fs.getFileStatus(new Path(handle.getPath()));  // throws FileNotFoundException if gone
handle.verify(stat);

Defensive patterns

Strategy: validation

Validate before calling

FileStatus st = fs.getFileStatus(new Path(handle.getPath())); // throws FileNotFoundException when gone
handle.verify(st);

Try / catch

try {
  handle.verify(stat);
} catch (InvalidPathHandleException e) {
  /* could not resolve: relocate the file or fail the operation */
}

Prevention

Resolve stats yourself and handle FileNotFoundException first
Never call verify(null)
Fix custom FileSystem wrappers to throw FileNotFoundException instead of returning null stats

When it happens

Trigger: Calling verify(stat) with a null FileStatus — usually a caller bug or a custom FileSystem/wrapper that returns null instead of throwing FileNotFoundException when the handle's path no longer resolves.

Common situations: File deleted or moved between handle capture and verification; wrapper filesystems returning null stats on ENOENT; unguarded Optional FileStatus lookups.

Related errors

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