{"record":{"id":"1c8494368b46b50e","repo":"apache/hadoop","slug":"file-exists-1c8494","errorCode":null,"errorMessage":"File exists","messagePattern":"File exists","errorType":"exception","errorClass":"PathExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/Mkdir.java","lineNumber":62,"sourceCode":"  public static final String USAGE = \"[-p] <path> ...\";\n  public static final String DESCRIPTION =\n    \"Create a directory in specified location.\\n\" +\n    \"-p: Do not fail if the directory already exists\";\n\n  private boolean createParents;\n  \n  @Override\n  protected void processOptions(LinkedList<String> args) {\n    CommandFormat cf = new CommandFormat(1, Integer.MAX_VALUE, \"p\");\n    cf.parse(args);\n    createParents = cf.getOpt(\"p\");\n  }\n\n  @Override\n  protected void processPath(PathData item) throws IOException {\n    if (item.stat.isDirectory()) {\n      if (!createParents) {\n        throw new PathExistsException(item.toString());\n      }\n    } else {\n      throw new PathIsNotDirectoryException(item.toString());\n    }\n  }\n\n  @Override\n  protected void processNonexistentPath(PathData item) throws IOException {\n    if (!createParents) {\n      // check if parent exists. this is complicated because getParent(a/b/c/) returns a/b/c, but\n      // we want a/b\n      final Path itemPath = new Path(item.path.toString());\n      final Path itemParentPath = itemPath.getParent();\n\n      if(itemParentPath == null) {\n        throw new PathNotFoundException(String.format(\n            \"Item: %s parent's path is null. This can happen if mkdir is \" +\n                \"called on root, so there's no parent.\", itemPath.toString()));","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/Mkdir.java#L44-L80","documentation":"PathExistsException ('File exists') thrown by Mkdir.processPath (Mkdir.java:62) when 'hadoop fs -mkdir' (without -p) is called on a path that already exists and is a directory. The non-parents mkdir is POSIX-strict: an existing directory is an error. With -p (createParents) the same situation is a no-op success.","triggerScenarios":"'hadoop fs -mkdir /data/exists' where /data/exists is already a directory; idempotent re-runs of provisioning scripts that do not use -p; race where two jobs mkdir the same staging path simultaneously.","commonSituations":"Deployment pipelines that provision the same directory each run; make-style targets without guards; onboarding docs using bare mkdir where -p was intended.","solutions":["Use -p for idempotent creation: 'hadoop fs -mkdir -p /data/exists' succeeds if the dir is already there","If a fresh directory is required, 'hadoop fs -rm -r /data/exists' first (accepting data loss), then mkdir","Pre-check with 'hadoop fs -test -d /path' when you must distinguish created vs already-existed"],"exampleFix":"# before\nhadoop fs -mkdir /staging/daily    # File exists on re-run\n\n# after\nhadoop fs -mkdir -p /staging/daily","handlingStrategy":"validation","validationCode":"if (fs.exists(path) && fs.getFileStatus(path).isDirectory()) {\n  // already exists: use mkdir -p semantics (no-op) instead of failing\n}","typeGuard":"static boolean mkdirNeeded(FileSystem fs, Path p) throws IOException {\n  return !fs.exists(p);\n}","tryCatchPattern":"try {\n  fs.mkdirs(path);\n} catch (PathExistsException e) {\n  // directory already present; treat as success for idempotent provisioning\n}","preventionTips":["Default to 'hadoop fs -mkdir -p' in scripts for idempotency","Use fs.mkdirs() in Java — it is a no-op on existing directories","Use -test -d when you must distinguish created vs pre-existing"],"tags":["hadoop","mkdir","shell","path-exists","idempotency"],"backgroundTag":"path-already-exists","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}