{"record":{"id":"e570bea4ea1e7d20","repo":"apache/hadoop","slug":"failed-to-create-directory-e570be","errorCode":null,"errorMessage":"Failed to create directory: {}","messagePattern":"Failed to create directory: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirMkdirOp.java","lineNumber":83,"sourceCode":"        if (!createParent) {\n          fsd.verifyParentDir(iip);\n        }\n\n        // validate that we have enough inodes. This is, at best, a\n        // heuristic because the mkdirs() operation might need to\n        // create multiple inodes.\n        fsn.checkFsObjectLimit();\n\n        // Ensure that the user can traversal the path by adding implicit\n        // u+wx permission to all ancestor directories.\n        INodesInPath existing =\n            createParentDirectories(fsd, iip, permissions, false);\n        if (existing != null) {\n          existing = createSingleDirectory(\n              fsd, existing, iip.getLastLocalName(), permissions);\n        }\n        if (existing == null) {\n          throw new IOException(\"Failed to create directory: \" + src);\n        }\n        iip = existing;\n      }\n      return fsd.getAuditFileInfo(iip);\n    } finally {\n      fsd.writeUnlock();\n    }\n  }\n\n  /**\n   * For a given absolute path, create all ancestors as directories along the\n   * path. All ancestors inherit their parent's permission plus an implicit\n   * u+wx permission. This is used by create() and addSymlink() for\n   * implicitly creating all directories along the path.\n   *\n   * For example, path=\"/foo/bar/spam\", \"/foo\" is an existing directory,\n   * \"/foo/bar\" is not existing yet, the function will create directory bar.\n   *","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirMkdirOp.java#L65-L101","documentation":"IOException ('Failed to create directory') raised when the internal unprotected mkdir could not add the new inode - fsd.addLastINode returned null, which happens when the namespace changed under the caller between path resolution and insertion. It is the NameNode's sentinel for a lost creation race (typically another client just created the same component); quota failures throw QuotaExceededException instead and a file in the way throws FileAlreadyExistsException.","triggerScenarios":"Two clients running `hdfs dfs -mkdir -p` on the same deep path concurrently; many parallel task attempts initializing a shared staging directory; a burst of retries right after a failed job submit.","commonSituations":"Highly concurrent job launchers (Oozie, Spark, workflow templates) creating common parent directories; parallelized init scripts across nodes; shared warehouse bootstrap code.","solutions":["Re-check the path: `hdfs dfs -test -d <path>` - if it now exists, the goal is met; continue.","Retry mkdirs; it is idempotent and a small bounded retry loop almost always resolves the race.","Create shared root directories once at deploy time so parallel jobs only mkdir distinct children."],"exampleFix":"// before\nfs.mkdirs(deepPath); // IOException: Failed to create directory (lost race)\n\n// after\nstatic void mkdirsRetry(FileSystem fs, Path p, int attempts) throws IOException {\n  IOException last = null;\n  for (int i = 0; i < attempts; i++) {\n    try { fs.mkdirs(p); return; }\n    catch (IOException e) {\n      last = e;\n      if (fs.exists(p) && fs.getFileStatus(p).isDirectory()) return; // race lost but dir exists\n    }\n  }\n  throw last;\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"static void mkdirsRetry(FileSystem fs, Path p, int attempts) throws IOException {\n  IOException last = null;\n  for (int i = 0; i < attempts; i++) {\n    try {\n      fs.mkdirs(p);\n      return;\n    } catch (IOException e) {\n      last = e;\n      // lost race but the outcome exists: done\n      if (fs.exists(p) && fs.getFileStatus(p).isDirectory()) return;\n    }\n  }\n  throw last;\n}","preventionTips":["Pre-create shared parent directories once at deploy time; parallel jobs then only create distinct leaves.","Always re-test -d after a failed mkdir before reporting an error.","Bound retries (2-3) with a short backoff; a persistent failure indicates a real problem, not a race."],"tags":["hdfs","mkdir","race-condition","concurrency"],"backgroundTag":"concurrent-modification","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}