apache/hadoop · error · IOException

Error " + result + " creating symlink " + link + " to " + ta

Error message

Error " + result + " creating symlink " + link + " to " + target

What it means

Thrown by RawLocalFileSystem.createSymlink when the underlying FileUtil.symLink shell call ('ln -s') returns a non-zero exit code. The numeric result is embedded in the message; it is the raw errno-mapped exit status of the ln process. Common exit codes: 1 (generic, e.g. permission denied or target syntax), 2 (missing operand/dangling parent). The IOException surfaces OS-level failures Hadoop does not otherwise classify.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java:1281

  public void createSymlink(Path target, Path link, boolean createParent)
      throws IOException {
    if (!FileSystem.areSymlinksEnabled()) {
      throw new UnsupportedOperationException("Symlinks not supported");
    }
    final String targetScheme = target.toUri().getScheme();
    if (targetScheme != null && !"file".equals(targetScheme)) {
      throw new IOException("Unable to create symlink to non-local file "+
                            "system: "+target.toString());
    }
    if (createParent) {
      mkdirs(link.getParent());
    }

    // NB: Use createSymbolicLink in java.nio.file.Path once available
    int result = FileUtil.symLink(target.toString(),
        makeAbsolute(link).toString());
    if (result != 0) {
      throw new IOException("Error " + result + " creating symlink " +
          link + " to " + target);
    }
  }

  /**
   * Return a FileStatus representing the given path. If the path refers
   * to a symlink return a FileStatus representing the link rather than
   * the object the link refers to.
   */
  @Override
  public FileStatus getFileLinkStatus(final Path f) throws IOException {
    FileStatus fi = getFileLinkStatusInternal(f, false);
    // getFileLinkStatus is supposed to return a symlink with a
    // qualified path
    if (fi.isSymlink()) {
      Path targetQual = FSLinkResolver.qualifySymlinkTarget(this.getUri(),
          fi.getPath(), fi.getSymlink());
      fi.setSymlink(targetQual);

View on GitHub (pinned to 2add963021)

Solutions

1. Reproduce manually: run 'ln -s <target> <link>' as the same user on the same host and read the shell error
2. Ensure the parent directory exists and is writable: createParent=true or mkdirs(link.getParent()) first
3. Delete an existing link before recreating: fs.delete(link, false)
4. Verify /bin/ln exists and symlinks are permitted on that mount/filesystem

Example fix

// before
rawFs.createSymlink(target, link, false);

// after
if (!rawFs.exists(link.getParent())) {
  rawFs.mkdirs(link.getParent());
}
rawFs.createSymlink(target, link, false);

if (!fs.exists(link.getParent())) {
  fs.mkdirs(link.getParent());
}
try {
  fs.getFileLinkStatus(link);
  fs.delete(link, false); // clear stale link
} catch (FileNotFoundException ignored) {
  // no existing link, good
}
fs.createSymlink(target, link, false);

try {
  fs.createSymlink(target, link, false);
} catch (IOException e) {
  // message contains "Error <N> creating symlink" - N is ln's exit status
  // 1: permission/exists, 2: missing operand -> verify parent and perms
  throw new IOException("ln -s failed for " + link + " -> " + target
      + "; check parent dir perms and mount support", e);
}

When it happens

Trigger: createSymlink where the link's parent directory does not exist (and createParent=false), the link already exists, the parent directory is not writable, the filesystem does not support symlinks (some mounts, container runtimes, or Windows without privileges), or /bin/ln is missing from PATH.

Common situations: Seccomp/container profiles blocking symlink syscalls; NFS/overlayfs mounts without symlink support; running as a user without write permission on the parent; PATH stripped by a minimal JVM environment so Shell cannot find 'ln'.

Related errors

• Symlinks not supported
• Unable to create symlink to non-local file system: " + targe
• Checksum file not a length multiple of checksum size in {} a
• Checksum error: {} at {}
• Checksum error: {} at {} exp: {} got: {}

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