apache/hadoop · error · FileNotFoundException

File {} not found.

Error message

File {} not found.

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/RouterWebHdfsMethods.java:516

        getTrimmedStringCollection(excludeDatanodes);
    for (DatanodeInfo dn : dns) {
      String ns = getNsFromDataNodeNetworkLocation(dn.getNetworkLocation());
      if (collection.contains(dn.getName())) {
        excludes.add(dn);
      } else if (op == PutOpParam.Op.CREATE && !ns.equals(resolvedNs)) {
        // for CREATE, the dest dn should be in the resolved ns
        excludes.add(dn);
      }
    }

    if (op == GetOpParam.Op.OPEN ||
        op == PostOpParam.Op.APPEND ||
        op == GetOpParam.Op.GETFILECHECKSUM) {
      // Choose a datanode containing a replica
      final ClientProtocol cp = getRpcClientProtocol();
      final HdfsFileStatus status = cp.getFileInfo(path);
      if (status == null) {
        throw new FileNotFoundException("File " + path + " not found.");
      }
      final long len = status.getLen();
      if (op == GetOpParam.Op.OPEN) {
        if (openOffset < 0L || (openOffset >= len && len > 0)) {
          throw new IOException("Offset=" + openOffset
              + " out of the range [0, " + len + "); " + op + ", path=" + path);
        }
      }

      if (len > 0) {
        final long offset = op == GetOpParam.Op.OPEN ? openOffset : len - 1;
        final LocatedBlocks locations = cp.getBlockLocations(path, offset, 1);
        final int count = locations.locatedBlockCount();
        if (count > 0) {
          LocatedBlock location0 = locations.get(0);
          return bestNode(location0.getLocations(), excludes);
        }
      }

View on GitHub (pinned to 2add963021)

Solutions

1. Verify the file exists through the Router first (hdfs dfs -ls, WebHDFS GETFILESTATUS) and re-check the path spelling
2. 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
3. Handle FileNotFoundException as an expected outcome in read paths (stale handles) rather than retrying it

// Pre-check existence through the Router before OPEN/APPEND/CHECKSUM:
HdfsFileStatus st = routerClient.getFileInfo(path);
if (st == null) {
  // do not attempt the WebHDFS open
}

catch (FileNotFoundException e) {
  // expected for stale paths: refresh listing, do not blindly retry
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Offset={} out of the range [0, {}); {}, path={}
• Router is in startup mode
• {} is not supported
• Failed to find datanode, suggest to check cluster health. ex
• Cannot find target file - {trg}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/2e0ec44d159b273f. Report an issue: GitHub.