{"record":{"id":"ce8cea84101daf70","repo":"apache/hadoop","slug":"could-not-resolve-handle-ce8cea","errorCode":null,"errorMessage":"Could not resolve handle","messagePattern":"Could not resolve handle","errorType":"exception","errorClass":"InvalidPathHandleException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/protocol/HdfsPathHandle.java","lineNumber":70,"sourceCode":"  public HdfsPathHandle(ByteBuffer bytes) throws IOException {\n    if (null == bytes) {\n      throw new IOException(\"Missing PathHandle\");\n    }\n    HdfsPathHandleProto p =\n        HdfsPathHandleProto.parseFrom(ByteString.copyFrom(bytes));\n    path = p.getPath();\n    mtime   = p.hasMtime()   ? p.getMtime()   : null;\n    inodeId = p.hasInodeId() ? p.getInodeId() : null;\n  }\n\n  public String getPath() {\n    return path;\n  }\n\n  public void verify(HdfsLocatedFileStatus stat)\n      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    if (inodeId != null && inodeId != stat.getFileId()) {\n      throw new InvalidPathHandleException(\"Wrong file\");\n    }\n  }\n\n  @Override\n  public ByteBuffer bytes() {\n    HdfsPathHandleProto.Builder b = HdfsPathHandleProto.newBuilder();\n    b.setPath(path);\n    if (inodeId != null) {\n      b.setInodeId(inodeId);\n    }\n    if (mtime != null) {\n      b.setMtime(mtime);","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/protocol/HdfsPathHandle.java#L52-L88","documentation":"HdfsPathHandle.verify(stat) throws InvalidPathHandleException('Could not resolve handle') when the resolved status is null, i.e. the path encoded in the handle no longer resolves to any file on the NameNode. PathHandles are HDFS's content/identity-addressed references (like file descriptors surviving rename); this is the 'file gone' case.","triggerScenarios":"Opening data via a PathHandle (FileSystem.open(PathHandle)) after the file was deleted, moved off cluster, or the handle was built from a different namespace (wrong cluster/URI).","commonSituations":"Reusing serialized PathHandles across cluster migrations or restores from backup; two jobs sharing a handle where one deletes the output; typos matching handle cluster to fs.defaultFS.","solutions":["Confirm the file still exists at handle.getPath() and that you are talking to the same cluster/namespace the handle was built from.","Recreate the handle from a fresh FileSystem instance if the file was re-created.","Treat this as unrecoverable for that handle: catch InvalidPathHandleException and regenerate upstream data."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Cheap pre-check that the handle's path still resolves before using the handle\nPath p = new Path(handle.getPath());\nif (!fs.exists(p)) {\n  // handle cannot resolve — regenerate data instead of calling open(handle)\n}","typeGuard":null,"tryCatchPattern":"try (FSDataInputStream in = fs.open(handle)) {\n  ...\n} catch (InvalidPathHandleException e) {\n  // 'Could not resolve handle': file gone or wrong cluster — unrecoverable for this handle\n}","preventionTips":["Bind handles to a stable cluster URI before persisting them.","Do not delete files that consumers hold handles to; write new generations to new paths.","Persist enough metadata (cluster, path, creation id) beside the handle to detect mismatch early."],"tags":["hdfs","path-handle","file-not-found","identity"],"backgroundTag":"stale-file-handle","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}