apache/hadoop · error · IOException

Missing PathHandle

Error message

Missing PathHandle

What it means

LocalFileSystemPathHandle is the PathHandle implementation for local files, serialized as protobuf bytes. The deserializing constructor demands a non-null ByteBuffer; passing null (no stored handle payload) throws this IOException before any parsing.

Source

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

import java.util.Objects;
import java.util.Optional;

/**
 * Opaque handle to an entity in a FileSystem.
 */
public class LocalFileSystemPathHandle implements PathHandle {

  private final String path;
  private final Long mtime;

  public LocalFileSystemPathHandle(String path, Optional<Long> mtime) {
    this.path = path;
    this.mtime = mtime.orElse(null);
  }

  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");
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Null-check the byte buffer before deserializing and fail fast or skip with a clear message
2. Persist PathHandle.bytes() at capture time so stored handles are never null
3. Represent 'no handle' as Optional.empty()/absent in your model instead of null

Example fix

// before
PathHandle h = new LocalFileSystemPathHandle(bytes);   // bytes == null
// after
if (bytes == null) throw new IOException("no PathHandle bytes stored");
PathHandle h = new LocalFileSystemPathHandle(bytes);

if (bytes == null) throw new IOException("no PathHandle bytes stored");
PathHandle h = new LocalFileSystemPathHandle(bytes);

When it happens

Trigger: new LocalFileSystemPathHandle((ByteBuffer) null), typically reached when a persisted handle field/metadata entry is empty and code feeds null bytes into handle deserialization instead of treating absence explicitly.

Common situations: Handle bytes never captured at write time, Optional.empty() handle representations forwarded as null, metadata schema where the handle column is nullable and unguarded.

Related errors

• mkdirs path arg is null
• parent + " is a file"
• Parent directory doesn't exist: " + parent
• absolutePath + ": No such file or directory."
• Exception while get content summary

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