apache/hadoop · error · FileNotFoundException

File does not exist: {f}

Error message

File does not exist: {f}

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/WebHdfsFileSystem.java:2238

        return new Path((String) json.get(Path.class.getSimpleName()));
      }
    }.run();
  }

  @Override
  public FileStatus getFileLinkStatus(Path f) throws IOException {
    statistics.incrementReadOps(1);
    storageStatistics.incrementOpCounter(OpType.GET_FILE_LINK_STATUS);
    final HttpOpParam.Op op = GetOpParam.Op.GETFILELINKSTATUS;
    HdfsFileStatus status =
        new FsPathResponseRunner<HdfsFileStatus>(op, f) {
          @Override
          HdfsFileStatus decodeResponse(Map<?, ?> json) {
            return JsonUtilClient.toFileStatus(json, true);
          }
        }.run();
    if (status == null) {
      throw new FileNotFoundException("File does not exist: " + f);
    }
    return status.makeQualified(getUri(), f);
  }

  @Override
  public FsStatus getStatus(Path path) throws IOException {
    statistics.incrementReadOps(1);
    storageStatistics.incrementOpCounter(OpType.GET_STATUS);
    final GetOpParam.Op op = GetOpParam.Op.GETSTATUS;
    return new FsPathResponseRunner<FsStatus>(op, path) {
      @Override
      FsStatus decodeResponse(Map<?, ?> json) {
        return JsonUtilClient.toFsStatus(json);
      }
    }.run();
  }

  public Collection<ErasureCodingPolicyInfo> getAllErasureCodingPolicies()

View on GitHub (pinned to 2add963021)

Solutions

1. 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)
2. If a pre-check fits better, call fs.exists(p) first, accepting the small race window
3. Verify the Path is fully qualified and built against the intended working directory
4. For symlink metadata without existence races, open with FsLinkResolver/FileContext APIs designed for link traversal

Example fix

// before
FileStatus st = fs.getFileLinkStatus(p); // throws if p is absent
// after
FileStatus st;
try {
  st = fs.getFileLinkStatus(p);
} catch (FileNotFoundException e) {
  st = null; // absent: handle gracefully
}

if (fs.exists(p)) {  // optional pre-check; still racy (TOCTOU)
  FileStatus st = fs.getFileLinkStatus(p);
}

FileStatus st = null;
try {
  st = fs.getFileLinkStatus(p);
} catch (FileNotFoundException e) {
  // expected for absent paths — treat as null, not an error
}

When it happens

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

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

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

• %s not found: %s
• Parent directory doesn't exist: {}
• Non existing file: ${path}. Create option is not specified i
• rename source ${src} not found.
• Filesystem does not support symlinks!

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