{"record":{"id":"2e0ec44d159b273f","repo":"apache/hadoop","slug":"file-not-found-2e0ec4","errorCode":null,"errorMessage":"File {} not found.","messagePattern":"File (.+?) not found\\.","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":404,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/RouterWebHdfsMethods.java","lineNumber":516,"sourceCode":"        getTrimmedStringCollection(excludeDatanodes);\n    for (DatanodeInfo dn : dns) {\n      String ns = getNsFromDataNodeNetworkLocation(dn.getNetworkLocation());\n      if (collection.contains(dn.getName())) {\n        excludes.add(dn);\n      } else if (op == PutOpParam.Op.CREATE && !ns.equals(resolvedNs)) {\n        // for CREATE, the dest dn should be in the resolved ns\n        excludes.add(dn);\n      }\n    }\n\n    if (op == GetOpParam.Op.OPEN ||\n        op == PostOpParam.Op.APPEND ||\n        op == GetOpParam.Op.GETFILECHECKSUM) {\n      // Choose a datanode containing a replica\n      final ClientProtocol cp = getRpcClientProtocol();\n      final HdfsFileStatus status = cp.getFileInfo(path);\n      if (status == null) {\n        throw new FileNotFoundException(\"File \" + path + \" not found.\");\n      }\n      final long len = status.getLen();\n      if (op == GetOpParam.Op.OPEN) {\n        if (openOffset < 0L || (openOffset >= len && len > 0)) {\n          throw new IOException(\"Offset=\" + openOffset\n              + \" out of the range [0, \" + len + \"); \" + op + \", path=\" + path);\n        }\n      }\n\n      if (len > 0) {\n        final long offset = op == GetOpParam.Op.OPEN ? openOffset : len - 1;\n        final LocatedBlocks locations = cp.getBlockLocations(path, offset, 1);\n        final int count = locations.locatedBlockCount();\n        if (count > 0) {\n          LocatedBlock location0 = locations.get(0);\n          return bestNode(location0.getLocations(), excludes);\n        }\n      }","sourceCodeStart":498,"sourceCodeEnd":534,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/RouterWebHdfsMethods.java#L498-L534","documentation":"Inside RouterWebHdfsMethods.chooseDatanode, for OPEN/APPEND/GETFILECHECKSUM the Router first resolves the file through its own RPC client (cp.getFileInfo(path)). A null status means no subcluster reports the file, so it cannot locate any replica to redirect to, and FileNotFoundException is thrown. This is the Router-level equivalent of trying to open a nonexistent file via WebHDFS.","triggerScenarios":"WebHDFS OPEN, APPEND or GETFILECHECKSUM for a path that does not exist in any namespace the Router resolves; file deleted between an ls and the open; path resolves to a different subcluster than where the file lives (stale mount table).","commonSituations":"Race with a concurrent delete/rename; clients using a cached file path after migration between namespaces; mount table changed so the path now resolves elsewhere.","solutions":["Verify the file exists through the Router first (hdfs dfs -ls, WebHDFS GETFILESTATUS) and re-check the path spelling","If the file exists in a subcluster but not via the Router, verify the mount-table entry maps that path to the right nameservice (hdfs dfsrouteradmin -ls) and refresh","Handle FileNotFoundException as an expected outcome in read paths (stale handles) rather than retrying it"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-check existence through the Router before OPEN/APPEND/CHECKSUM:\nHdfsFileStatus st = routerClient.getFileInfo(path);\nif (st == null) {\n  // do not attempt the WebHDFS open\n}","typeGuard":null,"tryCatchPattern":"catch (FileNotFoundException e) {\n  // expected for stale paths: refresh listing, do not blindly retry\n}","preventionTips":["Re-validate file existence immediately before read/append in workflows with concurrent deletes","Use fresh listings (not cached paths) when composing read requests","After mount-table changes, verify old paths still resolve before clients read them"],"tags":["hadoop","hdfs","rbf","webhdfs","file-not-found","open","append"],"backgroundTag":"file-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}