{"record":{"id":"b824fe2001f206f9","repo":"apache/hadoop","slug":"error-result-creating-symlink-link","errorCode":null,"errorMessage":"Error \" + result + \" creating symlink \" + link + \" to \" + target","messagePattern":"Error \" \\+ result \\+ \" creating symlink \" \\+ link \\+ \" to \" \\+ target","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java","lineNumber":1281,"sourceCode":"  public void createSymlink(Path target, Path link, boolean createParent)\n      throws IOException {\n    if (!FileSystem.areSymlinksEnabled()) {\n      throw new UnsupportedOperationException(\"Symlinks not supported\");\n    }\n    final String targetScheme = target.toUri().getScheme();\n    if (targetScheme != null && !\"file\".equals(targetScheme)) {\n      throw new IOException(\"Unable to create symlink to non-local file \"+\n                            \"system: \"+target.toString());\n    }\n    if (createParent) {\n      mkdirs(link.getParent());\n    }\n\n    // NB: Use createSymbolicLink in java.nio.file.Path once available\n    int result = FileUtil.symLink(target.toString(),\n        makeAbsolute(link).toString());\n    if (result != 0) {\n      throw new IOException(\"Error \" + result + \" creating symlink \" +\n          link + \" to \" + target);\n    }\n  }\n\n  /**\n   * Return a FileStatus representing the given path. If the path refers\n   * to a symlink return a FileStatus representing the link rather than\n   * the object the link refers to.\n   */\n  @Override\n  public FileStatus getFileLinkStatus(final Path f) throws IOException {\n    FileStatus fi = getFileLinkStatusInternal(f, false);\n    // getFileLinkStatus is supposed to return a symlink with a\n    // qualified path\n    if (fi.isSymlink()) {\n      Path targetQual = FSLinkResolver.qualifySymlinkTarget(this.getUri(),\n          fi.getPath(), fi.getSymlink());\n      fi.setSymlink(targetQual);","sourceCodeStart":1263,"sourceCodeEnd":1299,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java#L1263-L1299","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Reproduce manually: run 'ln -s <target> <link>' as the same user on the same host and read the shell error","Ensure the parent directory exists and is writable: createParent=true or mkdirs(link.getParent()) first","Delete an existing link before recreating: fs.delete(link, false)","Verify /bin/ln exists and symlinks are permitted on that mount/filesystem"],"exampleFix":"// before\nrawFs.createSymlink(target, link, false);\n\n// after\nif (!rawFs.exists(link.getParent())) {\n  rawFs.mkdirs(link.getParent());\n}\nrawFs.createSymlink(target, link, false);","handlingStrategy":"validation","validationCode":"if (!fs.exists(link.getParent())) {\n  fs.mkdirs(link.getParent());\n}\ntry {\n  fs.getFileLinkStatus(link);\n  fs.delete(link, false); // clear stale link\n} catch (FileNotFoundException ignored) {\n  // no existing link, good\n}\nfs.createSymlink(target, link, false);","typeGuard":null,"tryCatchPattern":"try {\n  fs.createSymlink(target, link, false);\n} catch (IOException e) {\n  // message contains \"Error <N> creating symlink\" - N is ln's exit status\n  // 1: permission/exists, 2: missing operand -> verify parent and perms\n  throw new IOException(\"ln -s failed for \" + link + \" -> \" + target\n      + \"; check parent dir perms and mount support\", e);\n}","preventionTips":["Create the parent directory and remove a stale link before createSymlink","Confirm the runtime user can write the parent and the filesystem permits symlinks (containers, overlayfs, Windows need privilege)"],"tags":["hadoop","local-filesystem","symlink","shell-command"],"backgroundTag":"shell-command-exit-code","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}