{"record":{"id":"85c0db079b169e95","repo":"apache/hadoop","slug":"could-not-resolve-handle","errorCode":null,"errorMessage":"Could not resolve handle","messagePattern":"Could not resolve handle","errorType":"exception","errorClass":"InvalidPathHandleException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/LocalFileSystemPathHandle.java","lineNumber":56,"sourceCode":"  }\n\n  public LocalFileSystemPathHandle(ByteBuffer bytes) throws IOException {\n    if (null == bytes) {\n      throw new IOException(\"Missing PathHandle\");\n    }\n    LocalFileSystemPathHandleProto p =\n        LocalFileSystemPathHandleProto.parseFrom(ByteString.copyFrom(bytes));\n    path = p.hasPath()   ? p.getPath()  : null;\n    mtime = p.hasMtime() ? p.getMtime() : null;\n  }\n\n  public String getPath() {\n    return path;\n  }\n\n  public void verify(FileStatus stat) throws InvalidPathHandleException {\n    if (null == stat) {\n      throw new InvalidPathHandleException(\"Could not resolve handle\");\n    }\n    if (mtime != null && mtime != stat.getModificationTime()) {\n      throw new InvalidPathHandleException(\"Content changed\");\n    }\n  }\n\n  @Override\n  public ByteBuffer bytes() {\n    LocalFileSystemPathHandleProto.Builder b =\n        LocalFileSystemPathHandleProto.newBuilder();\n    b.setPath(path);\n    if (mtime != null) {\n      b.setMtime(mtime);\n    }\n    return b.build().toByteString().asReadOnlyByteBuffer();\n  }\n\n  @Override","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/LocalFileSystemPathHandle.java#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"File deleted or moved between handle capture and verification; wrapper filesystems returning null stats on ENOENT; unguarded Optional FileStatus lookups.","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"],"exampleFix":"// before\nhandle.verify(stat);                        // stat == null\n// after\nFileStatus stat = fs.getFileStatus(new Path(handle.getPath()));  // throws FileNotFoundException if gone\nhandle.verify(stat);","handlingStrategy":"validation","validationCode":"FileStatus st = fs.getFileStatus(new Path(handle.getPath())); // throws FileNotFoundException when gone\nhandle.verify(st);","typeGuard":null,"tryCatchPattern":"try {\n  handle.verify(stat);\n} catch (InvalidPathHandleException e) {\n  /* could not resolve: relocate the file or fail the operation */\n}","preventionTips":["Resolve stats yourself and handle FileNotFoundException first","Never call verify(null)","Fix custom FileSystem wrappers to throw FileNotFoundException instead of returning null stats"],"tags":["path-handle","file-status","resolution"],"backgroundTag":"path-handle-resolution-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}