apache/hadoop · error · IOException

failed to create link {} either because the filename is inva

Error message

failed to create link {} either because the filename is invalid or the file exists

What it means

Error "failed to create link {} either because the filename is invalid or the file exists" thrown in apache/hadoop.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirSymlinkOp.java:65

      throw new InvalidPathException("Invalid target name: " + target);
    }

    if (NameNode.stateChangeLog.isDebugEnabled()) {
      NameNode.stateChangeLog.debug("DIR* NameSystem.createSymlink: target="
          + target + " link=" + link);
    }

    FSPermissionChecker pc = fsn.getPermissionChecker();
    INodesInPath iip;
    fsd.writeLock();
    try {
      iip = fsd.resolvePath(pc, link, DirOp.WRITE_LINK);
      link = iip.getPath();
      if (!createParent) {
        fsd.verifyParentDir(iip);
      }
      if (!fsd.isValidToCreate(link, iip)) {
        throw new IOException(
            "failed to create link " + link +
                " either because the filename is invalid or the file exists");
      }
      if (fsd.isPermissionEnabled()) {
        fsd.checkAncestorAccess(pc, iip, FsAction.WRITE);
      }
      // validate that we have enough inodes.
      fsn.checkFsObjectLimit();

      // add symbolic link to namespace
      addSymlink(fsd, link, iip, target, dirPerms, createParent, logRetryCache);
    } finally {
      fsd.writeUnlock();
    }
    NameNode.getNameNodeMetrics().incrCreateSymlinkOps();
    return fsd.getAuditFileInfo(iip);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Ensure the link name is valid and does not already exist; remove the existing entry or choose another name.

When it happens

Trigger: Creating a symlink fails because the link name is invalid or an inode already exists at that path.

Common situations: See trigger scenarios.

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