{"record":{"id":"14e56449b7bea974","repo":"apache/hadoop","slug":"file-does-not-exist-14e564","errorCode":null,"errorMessage":"File {} does not exist.","messagePattern":"File (.+?) does not exist\\.","errorType":"http","errorClass":"FileNotFoundException","httpStatus":404,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/web/resources/NamenodeWebHdfsMethods.java","lineNumber":1694,"sourceCode":"    int start = 0;\n    if ((path.length() == start) || // empty path\n        (lastSlash == start && path.length() == start + 1)) { // at root\n      return null;\n    }\n    String parent;\n    if (lastSlash == -1) {\n      parent = org.apache.hadoop.fs.Path.CUR_DIR;\n    } else {\n      parent = path.substring(0, lastSlash == start ? start + 1 : lastSlash);\n    }\n    return parent;\n  }\n\n  private static DirectoryListing getDirectoryListing(final ClientProtocol cp,\n      final String p, byte[] startAfter) throws IOException {\n    final DirectoryListing listing = cp.getListing(p, startAfter, false);\n    if (listing == null) { // the directory does not exist\n      throw new FileNotFoundException(\"File \" + p + \" does not exist.\");\n    }\n    return listing;\n  }\n  \n  private static StreamingOutput getListingStream(final ClientProtocol cp,\n      final String p) throws IOException {\n    // allows exceptions like FNF or ACE to prevent http response of 200 for\n    // a failure since we can't (currently) return error responses in the\n    // middle of a streaming operation\n    final DirectoryListing firstDirList = getDirectoryListing(cp, p,\n        HdfsFileStatus.EMPTY_NAME);\n\n    // must save ugi because the streaming object will be executed outside\n    // the remote user's ugi\n    final UserGroupInformation ugi = UserGroupInformation.getCurrentUser();\n    return new StreamingOutput() {\n      @Override\n      public void write(final OutputStream outstream) throws IOException {","sourceCodeStart":1676,"sourceCodeEnd":1712,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/web/resources/NamenodeWebHdfsMethods.java#L1676-L1712","documentation":"Helper behind GET op=LISTSTATUS. ClientProtocol.getListing returns null when the path is not an existing directory, and getDirectoryListing turns that into FileNotFoundException('File <p> does not exist.') -> HTTP 404. Per the code comment, the first listing page is fetched before the HTTP 200 body starts streaming, precisely so this failure does not get stuck mid-response; the same helper also serves pagination (startAfter), so a directory deleted mid-listing fails on the next page.","triggerScenarios":"op=LISTSTATUS on a deleted or never-existing directory; on a plain file (getListing only lists directories, so a regular file also yields this misleading 'does not exist' message); pagination continuing after the directory was removed between pages.","commonSituations":"Directory cleanup racing a UI/job listing; LISTSTATUS issued where GETFILESTATUS was meant (file vs directory); tools assuming a fixed directory exists after a re-layout.","solutions":["Confirm the path exists and is a directory first (op=GETFILESTATUS then check isDirectory)","If listing a file was intended, use op=GETFILESTATUS — LISTSTATUS is for directories only","On 404 mid-pagination, stop and re-list from the parent; the directory changed underneath you","Encode the path exactly (spaces, %, #) before sending"],"exampleFix":"# before\ncurl \"http://nn:9870/webhdfs/v1/data/old_dir?op=LISTSTATUS\"   # 404 File /data/old_dir does not exist.\ncurl \"http://nn:9870/webhdfs/v1/data/file.txt?op=LISTSTATUS\" # 404 too: files cannot be LISTSTATUSed\n\n# after\ncurl \"http://nn:9870/webhdfs/v1/data/file.txt?op=GETFILESTATUS\"  # file -> use status, not listing\ncurl \"http://nn:9870/webhdfs/v1/data/new_dir?op=LISTSTATUS\"      # directory -> 200","handlingStrategy":"try-catch","validationCode":"FileStatus st = webhdfs.getFileStatus(dir);\nif (!st.isDirectory()) {\n  throw new IllegalArgumentException(dir + \" is a file; LISTSTATUS requires a directory\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  listing = getDirectoryListing(cp, dir, HdfsFileStatus.EMPTY_NAME);\n} catch (FileNotFoundException e) { // 404: dir deleted, or path is a file\n  return ListingResult.absent(dir);\n}","preventionTips":["Check isDirectory before LISTSTATUS when the path type is uncertain","Handle 404 on pagination pages: stop paging and re-list the parent","Do not assume LISTSTATUS on a file returns a one-entry listing — HDFS rejects it"],"tags":["webhdfs","hdfs","file-not-found","liststatus","rest-api","http-404"],"backgroundTag":"file-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}