{"record":{"id":"709b572ac02dda1c","repo":"apache/hadoop","slug":"file-does-not-exist-f-709b57","errorCode":null,"errorMessage":"File does not exist: {f}","messagePattern":"File does not exist: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/WebHdfsFileSystem.java","lineNumber":2238,"sourceCode":"        return new Path((String) json.get(Path.class.getSimpleName()));\n      }\n    }.run();\n  }\n\n  @Override\n  public FileStatus getFileLinkStatus(Path f) throws IOException {\n    statistics.incrementReadOps(1);\n    storageStatistics.incrementOpCounter(OpType.GET_FILE_LINK_STATUS);\n    final HttpOpParam.Op op = GetOpParam.Op.GETFILELINKSTATUS;\n    HdfsFileStatus status =\n        new FsPathResponseRunner<HdfsFileStatus>(op, f) {\n          @Override\n          HdfsFileStatus decodeResponse(Map<?, ?> json) {\n            return JsonUtilClient.toFileStatus(json, true);\n          }\n        }.run();\n    if (status == null) {\n      throw new FileNotFoundException(\"File does not exist: \" + f);\n    }\n    return status.makeQualified(getUri(), f);\n  }\n\n  @Override\n  public FsStatus getStatus(Path path) throws IOException {\n    statistics.incrementReadOps(1);\n    storageStatistics.incrementOpCounter(OpType.GET_STATUS);\n    final GetOpParam.Op op = GetOpParam.Op.GETSTATUS;\n    return new FsPathResponseRunner<FsStatus>(op, path) {\n      @Override\n      FsStatus decodeResponse(Map<?, ?> json) {\n        return JsonUtilClient.toFsStatus(json);\n      }\n    }.run();\n  }\n\n  public Collection<ErasureCodingPolicyInfo> getAllErasureCodingPolicies()","sourceCodeStart":2220,"sourceCodeEnd":2256,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/WebHdfsFileSystem.java#L2220-L2256","documentation":"WebHdfsFileSystem.getFileLinkStatus throws FileNotFoundException when the GETFILELINKSTATUS response decodes to a null HdfsFileStatus, i.e. the NameNode reports no entry at that path. Unlike getFileStatus, this call describes the symlink itself and does not resolve it, but a missing path still yields null on the server. This is standard FileSystem contract behavior: absent paths are signaled via FileNotFoundException.","triggerScenarios":"Calling fs.getFileLinkStatus(p) for a path that does not exist in the namespace (regular file, directory, or symlink); also races where the entry is deleted between an exists() check and this call.","commonSituations":"Checking whether a path is a symlink by probing getFileLinkStatus; TOCTOU races in cleanup jobs; typos or unqualified relative paths resolving against the wrong working directory; symlink-aware listing code that assumes an entry still exists.","solutions":["Catch FileNotFoundException and treat it as 'no such path' — this is the idiomatic pattern, faster than an exists() pre-check (one round trip instead of two)","If a pre-check fits better, call fs.exists(p) first, accepting the small race window","Verify the Path is fully qualified and built against the intended working directory","For symlink metadata without existence races, open with FsLinkResolver/FileContext APIs designed for link traversal"],"exampleFix":"// before\nFileStatus st = fs.getFileLinkStatus(p); // throws if p is absent\n// after\nFileStatus st;\ntry {\n  st = fs.getFileLinkStatus(p);\n} catch (FileNotFoundException e) {\n  st = null; // absent: handle gracefully\n}","handlingStrategy":"try-catch","validationCode":"if (fs.exists(p)) {  // optional pre-check; still racy (TOCTOU)\n  FileStatus st = fs.getFileLinkStatus(p);\n}","typeGuard":null,"tryCatchPattern":"FileStatus st = null;\ntry {\n  st = fs.getFileLinkStatus(p);\n} catch (FileNotFoundException e) {\n  // expected for absent paths — treat as null, not an error\n}","preventionTips":["Treat FileNotFoundException as a normal result for existence probing (one round trip)","Fully qualify Paths before status calls to avoid working-directory surprises","For listings, use listStatus which returns absent directories as empty rather than throwing in most cases"],"tags":["webhdfs","file-not-found","symlink","filesystem"],"backgroundTag":"file-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}