What causes "/ is not a file. The directory / already exist at: {}" in apache/hadoop?

Create the file under a concrete mounted path (e.g. viewfs:///user/alice/marker)

apache/hadoop · error · FileAlreadyExistsException

/ is not a file. The directory / already exist at: {}

Error message

/ is not a file. The directory / already exist at: {}

What it means

InternalDirOfViewFs.createInternal (the FileContext-side ViewFs implementation) rejects file creation at the root of an internal mount-table directory: if the remaining path equals InodeTree.SlashPath ("/"), it throws FileAlreadyExistsException("/ is not a file. The directory / already exist at: <internalDirPath>"). A virtual directory cannot become a file, and the root internal dir always exists.

Source

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

    static private void checkPathIsSlash(final Path f) throws IOException {
      if (f != InodeTree.SlashPath) {
        throw new IOException (
        "Internal implementation error: expected file name to be /" );
      }
    }

    @Override
    public FSDataOutputStream createInternal(final Path f,
        final EnumSet<CreateFlag> flag, final FsPermission absolutePermission,
        final int bufferSize, final short replication, final long blockSize,
        final Progressable progress, final ChecksumOpt checksumOpt,
        final boolean createParent) throws AccessControlException,
        FileAlreadyExistsException, FileNotFoundException,
        ParentNotDirectoryException, UnsupportedFileSystemException,
        UnresolvedLinkException, IOException {
      Preconditions.checkNotNull(f, "File cannot be null.");
      if (InodeTree.SlashPath.equals(f)) {
        throw new FileAlreadyExistsException(
            "/ is not a file. The directory / already exist at: "
                + theInternalDir.fullPath);
      }

      if (this.fsState.getRootFallbackLink() != null) {
        if (theInternalDir.getChildren().containsKey(f.getName())) {
          throw new FileAlreadyExistsException(
              "A mount path(file/dir) already exist with the requested path: "
                  + theInternalDir.getChildren().get(f.getName()).fullPath);
        }

        AbstractFileSystem linkedFallbackFs =
            this.fsState.getRootFallbackLink().getTargetFileSystem();
        Path parent = Path.getPathWithoutSchemeAndAuthority(
            new Path(theInternalDir.fullPath));
        String leaf = f.getName();
        Path fileToCreate = new Path(parent, leaf);

View on GitHub (pinned to 2add963021)

Solutions

Create the file under a concrete mounted path (e.g. viewfs:///user/alice/marker)
Mount the intended parent directory with fs.viewfs.mounttable.<n>.link.<parent>
Check path.isRoot() before create and reject early with a clear message

Example fix

// before
fc.create(new Path("viewfs:///"), EnumSet.of(CreateFlag.CREATE)); // throws

// after
Path p = new Path("viewfs:///user/alice/marker");
if (p.isRoot()) { throw new IllegalArgumentException("refusing to create file at viewfs root"); }
fc.create(p, EnumSet.of(CreateFlag.CREATE));

Defensive patterns

Strategy: validation

Validate before calling

static Path validateCreatePath(Path p) {
  if (p.isRoot() || p.toUri().getPath().equals("/")) {
    throw new IllegalArgumentException("Cannot create a file at viewfs root '/': pick a mounted path");
  }
  return p;
}

Try / catch

try {
  out = fc.create(p, EnumSet.of(CreateFlag.CREATE));
} catch (FileAlreadyExistsException fae) {
  if (fae.getMessage().startsWith("/ is not a file")) { /* p resolved to mount-table root */ }
}

Prevention

Reject Path.isRoot() in create/touch helpers up front
Ensure job home/staging dirs are mounted so parents never collapse to '/'

When it happens

Trigger: FileContext.create(new Path("viewfs:///"), ...) or any create whose resolution leaves remainingPath=="/" on an internal dir (e.g. creating the mount-table node /data itself when /data only contains links); touch/mkfile-style utilities targeting the viewfs root.

Common situations: Job/setup scripts creating sentinel files at the namespace root; Hive staging logic computing a parent that collapses to "/" because the user home mount is missing.

Related errors

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