{"record":{"id":"e34bb748c557c91a","repo":"apache/hadoop","slug":"a-file-cannot-be-created-in-root","errorCode":null,"errorMessage":"A file cannot be created in root.","messagePattern":"A file cannot be created in root\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/GoogleCloudStorageFileSystem.java","lineNumber":555,"sourceCode":"\n  private List<FileInfo> getFileInfos(List<URI> paths) throws IOException {\n    List<FileInfo> result = new ArrayList<>(paths.size());\n    for (URI path : paths) {\n      // TODO: Do this concurrently\n      result.add(getFileInfo(path));\n    }\n\n    return result;\n  }\n\n  private URI getDstUri(FileInfo srcInfo, FileInfo dstInfo, @Nullable FileInfo dstParentInfo)\n      throws IOException {\n    URI src = srcInfo.getPath();\n    URI dst = dstInfo.getPath();\n\n    // Throw if src is a file and dst == GCS_ROOT\n    if (!srcInfo.isDirectory() && dst.equals(GCSROOT)) {\n      throw new IOException(\"A file cannot be created in root.\");\n    }\n\n    // Throw if the destination is a file that already exists, and it's not a source file.\n    if (dstInfo.exists() && !dstInfo.isDirectory() && (srcInfo.isDirectory() || !dst.equals(src))) {\n      throw new IOException(\"Cannot overwrite an existing file: \" + dst);\n    }\n\n    // Rename operation cannot be completed if parent of destination does not exist.\n    if (dstParentInfo != null && !dstParentInfo.exists()) {\n      throw new IOException(\n          \"Cannot rename because path does not exist: \" + dstParentInfo.getPath());\n    }\n\n    // Leaf item of the source path.\n    String srcItemName = getItemName(src);\n\n    // Having taken care of the initial checks, apply the regular rules.\n    // After applying the rules, we will be left with 2 paths such that:","sourceCodeStart":537,"sourceCodeEnd":573,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/GoogleCloudStorageFileSystem.java#L537-L573","documentation":"getDstUri throws IOException(\"A file cannot be created in root.\") during rename when the source is a FILE and the destination equals GCSROOT (gs:// with no bucket). Root has no bucket to contain an object, so the move is impossible; directory sources proceed to other checks, and a missing destination parent is reported with a different message.","triggerScenarios":"rename(file, gs://) — the destination URI is exactly root, typically produced by parent-path arithmetic that walked above the bucket level (getParent on a bucket-root path) or an empty user-supplied destination.","commonSituations":"Path code stripping one segment too many; destination computed as getParent(src) of an already-bucket-level path; empty or misparsed destination URIs from configuration.","solutions":["Fix destination computation so dst always includes a bucket and a non-empty object name.","Validate dst against the root URI (and for emptiness) before calling rename.","For 'move to default bucket' semantics, resolve an explicit bucket path instead of gs://."],"exampleFix":"// before\nURI dst = UriPaths.getParentPath(srcPath); // walked above bucket -> gs://\nfs.rename(srcPath, dst); // 'A file cannot be created in root.'\n\n// after\ncheckArgument(!dst.equals(GCSROOT) && !dst.getPath().equals(\"/\"), \"dst must name a bucket + object\");\nfs.rename(srcPath, dst);","handlingStrategy":"validation","validationCode":"checkArgument(!dst.equals(GCSROOT) && dst.getBucket() != null\n    && !dst.getObjectName().isEmpty(),\n    \"rename destination must be bucket + object, got: %s\", dst);\ngcsFs.rename(src, dst);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate that destination URIs always carry a bucket and non-empty object name.","Never call getParentPath() past the bucket level — guard the walk with a bucket check.","Reject empty destination strings at the configuration/API boundary."],"tags":["gcs","rename","root-path","path-validation"],"backgroundTag":"rename-to-filesystem-root","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}