apache/hadoop · error · FileAlreadyExistsException

/ already exits

Error message

/ already exits

What it means

ViewFileSystem.InternalDir.mkdirs guards against a null directory argument at the mount-table root with FileAlreadyExistsException('/ already exits') (message typo is in the source). The root internal dir always exists, so creating it is a no-op at best; a null dir indicates a caller bug and is rejected explicitly.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/ViewFileSystem.java:1690

      long[] summary = {0, 0, 0};
      for (FileStatus status : listStatus(p)) {
        Path targetPath =
            Path.getPathWithoutSchemeAndAuthority(status.getPath());
        InodeTree.ResolveResult<FileSystem> res =
            fsState.resolve(targetPath.toString(), true);
        FsStatus child = res.targetFileSystem.getStatus(res.remainingPath);
        summary[0] += child.getCapacity();
        summary[1] += child.getUsed();
        summary[2] += child.getRemaining();
      }
      return new FsStatus(summary[0], summary[1], summary[2]);
    }

    @Override
    public boolean mkdirs(Path dir, FsPermission permission)
        throws IOException {
      if (theInternalDir.isRoot() && dir == null) {
        throw new FileAlreadyExistsException("/ already exits");
      }
      // Note dir starts with /
      if (theInternalDir.getChildren().containsKey(
          dir.toString().substring(1))) {
        return true; // this is the stupid semantics of FileSystem
      }

      if (this.fsState.getRootFallbackLink() != null) {
        FileSystem linkedFallbackFs =
            this.fsState.getRootFallbackLink().getTargetFileSystem();
        Path parent = Path.getPathWithoutSchemeAndAuthority(
            new Path(theInternalDir.fullPath));
        String leafChild = (InodeTree.SlashPath.equals(dir)) ?
            InodeTree.SlashPath.toString() :
            dir.getName();
        Path dirToCreate = new Path(parent, leafChild);

        try {

View on GitHub (pinned to 2add963021)

Solutions

1. Fix the caller to pass a concrete Path; FileSystem.mkdirs(null) is invalid API use
2. Add a null/empty guard before calling mkdirs and construct the intended directory path explicitly
3. If the intent was to ensure '/', drop the call - the viewfs root always exists
4. Catch FileAlreadyExistsException defensively in generic filesystem wrappers and log the offending argument

Example fix

// before
fs.mkdirs(null); // caller bug -> FileAlreadyExistsException("/ already exits")

// after
Path dir = targetDir != null ? targetDir : new Path("/");
if (!dir.isRoot()) {
  fs.mkdirs(dir);
}

// Null-check before mkdirs
java.util.Objects.requireNonNull(dir, "mkdirs target must not be null");
if (!dir.isRoot()) {
  fs.mkdirs(dir);
}

try {
  fs.mkdirs(dir);
} catch (FileAlreadyExistsException e) {
  // dir was null or '/' on the viewfs root internal dir: nothing to create
  LOG.debug("root exists; skipping mkdirs", e);
}

When it happens

Trigger: Some caller invokes mkdirs(null) on a FileSystem that resolves to the viewfs root internal dir - typically a wrapper that stripped a path component and passed null, or custom code that assumes mkdirs accepts null. The check only fires when theInternalDir.isRoot() and dir == null.

Common situations: Buggy path-manipulation code building parent paths and passing null for the root; older third-party libraries calling mkdirs with a possibly-null Path; rarely hit because it requires both root internal dir and null argument.

Related errors

• Can't make directory for path '%s' since it is a file.
• Cannot create directories because of existing file: %s
• Mkdirs failed to create {} (exists={}, cwd={})
• Not implemented by the ${getClass().getSimpleName()} FileSys
• Missing parent:${f}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/0792aaa81871e61d. Report an issue: GitHub.