{"record":{"id":"21e8282499864da8","repo":"apache/hadoop","slug":"can-t-create-root-path","errorCode":null,"errorMessage":"Can't create root path","messagePattern":"Can't create root path","errorType":"exception","errorClass":"PathIOException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AFileSystem.java","lineNumber":2100,"sourceCode":"   * If true, this method call does no IO at all.\n   * @param path the file name to open\n   * @param progress the progress reporter.\n   * @param auditSpan audit span\n   * @param options options for the file\n   * @throws IOException in the event of IO related errors.\n   */\n  @SuppressWarnings(\"IOResourceOpenedButNotSafelyClosed\")\n  @Retries.RetryTranslated\n  private FSDataOutputStream innerCreateFile(\n      final Path path,\n      final Progressable progress,\n      final AuditSpan auditSpan,\n      final CreateFileBuilder.CreateFileOptions options) throws IOException {\n    auditSpan.activate();\n    String key = pathToKey(path);\n    if (key.isEmpty()) {\n      // no matter the creation options, root cannot be written to.\n      throw new PathIOException(\"/\", \"Can't create root path\");\n    }\n    EnumSet<CreateFlag> flags = options.getFlags();\n\n    /*\n     Calculate whether to perform HEAD/LIST checks,\n     and whether the conditional create option should be set.\n     This seems complicated, but comes down to\n     \"if explicitly requested and the FS enables it, use\".\n     */\n    // create file attributes\n    boolean cCreate = options.isConditionalOverwrite();\n    boolean cEtag = options.isConditionalOverwriteEtag();\n    boolean createPerf = options.isPerformance();\n    boolean overwrite = flags.contains(CreateFlag.OVERWRITE);\n\n    // path attributes\n    boolean magic = isUnderMagicCommitPath(path);\n","sourceCodeStart":2082,"sourceCodeEnd":2118,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AFileSystem.java#L2082-L2118","documentation":"innerCreateFile() converts the target Path to an S3 object key with pathToKey(); the filesystem root (s3a://bucket/ or /) maps to the empty string, and S3 has no zero-length object key. So any create whose path resolves to the bucket root fails immediately with PathIOException on path '/' before any create flag is examined - neither overwrite, performance nor conditional options bypass it.","triggerScenarios":"fs.create(new Path(\"s3a://bucket/\")) or create(new Path(\"/\")); building a Path from a blank or missing filename; concatenating a parent string with a null child element so the result normalizes to the root.","commonSituations":"Paths assembled from unvalidated user or config input where the output filename is empty; walking getParent() one level too far; a blank output-file property making the job write to the bucket root.","solutions":["Fix the caller to pass a path with a real, non-empty last component (the object key)","Validate that path.getName() / the configured filename is non-empty before calling create","Log the exact path at the call site so mis-built paths surface immediately"],"exampleFix":"// before\nfs.create(new Path(\"s3a://\" + bucket + \"/\" + fileName));\n\n// after: reject blank names before touching S3A\nif (fileName == null || fileName.trim().isEmpty()) {\n  throw new IllegalArgumentException(\"fileName must not be empty\");\n}\nfs.create(new Path(new Path(\"s3a://\" + bucket + \"/\"), fileName));","handlingStrategy":"validation","validationCode":"static Path requireFileTarget(Path p) {\n  if (p.isRoot() || p.toUri().getPath().equals(\"/\")) {\n    throw new IllegalArgumentException(\"Refusing to create at filesystem root: \" + p);\n  }\n  return p;\n}","typeGuard":null,"tryCatchPattern":"If paths arrive from frameworks and cannot be pre-checked, catch PathIOException from create(), inspect getPath() and the message, and map 'Can't create root path' to an input-validation error rather than a retriable failure.","preventionTips":["Build paths with new Path(parent, child), never string concatenation of unvalidated parts","Reject blank output filenames at the CLI/config layer","Assert !path.isRoot() in test fixtures that create files"],"tags":["s3a","path","root","create","invalid-argument"],"backgroundTag":"write-to-filesystem-root","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}