{"record":{"id":"f3a150f297252253","repo":"apache/hadoop","slug":"file-does-not-exist-f3a150","errorCode":null,"errorMessage":"File does not exist: {}","messagePattern":"File does not exist: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeFile.java","lineNumber":87,"sourceCode":"  /**\n   * Erasure Coded striped blocks have replication factor of 1.\n   */\n  public static final short DEFAULT_REPL_FOR_STRIPED_BLOCKS = 1;\n\n  /** The same as valueOf(inode, path, false). */\n  public static INodeFile valueOf(INode inode, String path\n      ) throws FileNotFoundException {\n    return valueOf(inode, path, false);\n  }\n\n  /** Cast INode to INodeFile. */\n  public static INodeFile valueOf(INode inode, String path, boolean acceptNull)\n      throws FileNotFoundException {\n    if (inode == null) {\n      if (acceptNull) {\n        return null;\n      } else {\n        throw new FileNotFoundException(\"File does not exist: \" + path);\n      }\n    }\n    if (!inode.isFile()) {\n      throw new FileNotFoundException(\"Path is not a file: \" + path);\n    }\n    return inode.asFile();\n  }\n\n  /** \n   * Bit format:\n   * [4-bit storagePolicyID][12-bit BLOCK_LAYOUT_AND_REDUNDANCY]\n   * [48-bit preferredBlockSize]\n   *\n   * BLOCK_LAYOUT_AND_REDUNDANCY contains 12 bits and describes the layout and\n   * redundancy of a block. We use the highest 1 bit to determine whether the\n   * block is replica or erasure coded. For replica blocks, the tail 11 bits\n   * stores the replication factor. For erasure coded blocks, the tail 11 bits\n   * stores the EC policy ID, and in the future, we may further divide these","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeFile.java#L69-L105","documentation":"INodeFile.valueOf(INode, String) throws FileNotFoundException(\"File does not exist: <path>\") when the INode resolves to null and acceptNull is false (the one-arg overload hard-codes false). It is the internal cast helper for code paths that require an existing regular file; a null INode means the file was deleted or never existed.","triggerScenarios":"Resolving a deleted or never-created file through the single-arg valueOf; a concurrent delete between the client's existence check and the NameNode's processing; append/open flows on files removed by a cleanup job.","commonSituations":"Application retry loops racing with lifecycle/cleaner jobs; stale cached paths; idempotent writers assuming the file still exists.","solutions":["Handle FileNotFoundException as a normal 'file gone' signal — recreate the file or return not-found to the caller","If a null result is acceptable at the call site (e.g. best-effort cleanup), use the three-arg overload valueOf(inode, path, true)","Guard with an existence check only when you must distinguish races from genuine absence"],"exampleFix":"// before\nINodeFile file = INodeFile.valueOf(inode, path); // null inode -> throws\n\n// after\nINodeFile file = INodeFile.valueOf(inode, path, /* acceptNull */ true);\nif (file == null) {\n  // file already gone: treat as success for idempotent delete-style flows\n}","handlingStrategy":"validation","validationCode":"// NN-side: when absence is a valid state, ask for null instead of an exception\nINodeFile file = INodeFile.valueOf(fsDir.getINode(path, DirOp.READ), path, /*acceptNull*/ true);\nif (file == null) {\n  return; // already absent — idempotent no-op\n}","typeGuard":null,"tryCatchPattern":"catch (FileNotFoundException e) {\n  // Distinguish by message: 'File does not exist' vs 'Path is not a file'\n  if (e.getMessage() != null && e.getMessage().startsWith(\"File does not exist\")) {\n    return absentResult();   // treat as gone / 404\n  }\n  throw e;\n}","preventionTips":["Use the 3-arg valueOf(inode, path, acceptNull=true) whenever null is meaningful at the call site","Treat FileNotFoundException from these helpers as normal control flow for deleted files, not as bugs","Design clients idempotent to deletion races (check-exists pattern is inherently racy)"],"tags":["hdfs","namenode","file-not-found","race-condition","namespace"],"backgroundTag":"path-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}