{"record":{"id":"dc7eac79b4871e3a","repo":"apache/hadoop","slug":"unable-to-create-symlink-to-non-local-file-system","errorCode":null,"errorMessage":"Unable to create symlink to non-local file system: \" + target.toString()","messagePattern":"Unable to create symlink to non-local file system: \" \\+ target\\.toString\\(\\)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java","lineNumber":1270,"sourceCode":"        : Optional.empty();\n    return new LocalFileSystemPathHandle(p.toString(), mtime);\n  }\n\n  @Override\n  public boolean supportsSymlinks() {\n    return true;\n  }\n\n  @SuppressWarnings(\"deprecation\")\n  @Override\n  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","sourceCodeStart":1252,"sourceCodeEnd":1288,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java#L1252-L1288","documentation":"Thrown by RawLocalFileSystem.createSymlink when the symlink target's URI scheme is present and is not \"file\". A local symlink must point at a local path; Hadoop refuses to create a local link pointing at a remote namespace such as hdfs:// or s3a:// because the target would be meaningless outside the Hadoop client. The throw is an IOException, not UnsupportedOperationException, so it signals a bad argument rather than a missing feature.","triggerScenarios":"createSymlink(new Path(\"hdfs://nn/data\"), link, true); also any qualified path whose scheme is non-null and non-file, e.g. \"s3a://bucket/key\" or \"viewfs://cluster/...\".","commonSituations":"Attempting to mirror HDFS directory trees locally with symlinks; code that string-qualifies paths (Path.makeQualified against the default FS) before passing them as symlink targets.","solutions":["Pass an unqualified or file:// target: createSymlink(new Path(\"/local/data\"), link, true)","Use a manifest/reference file listing the hdfs:// location instead of a symlink","Pre-check the scheme and reject non-local targets with your own clear error before calling createSymlink"],"exampleFix":"// before\nrawFs.createSymlink(new Path(\"hdfs://nn/data\"), link, true); // IOException\n\n// after\nrawFs.createSymlink(new Path(\"/local/data\"), link, true); // local target","handlingStrategy":"validation","validationCode":"String scheme = target.toUri().getScheme();\nif (scheme != null && !\"file\".equals(scheme)) {\n  throw new IOException(\"Refusing non-local symlink target: \" + target);\n}\nfs.createSymlink(target, link, true);","typeGuard":null,"tryCatchPattern":"try {\n  fs.createSymlink(target, link, true);\n} catch (IOException e) {\n  // message starts with \"Unable to create symlink to non-local file system\"\n  throw new IllegalArgumentException(\"Symlink target must be local: \" + target, e);\n}","preventionTips":["Symlink only unqualified or file:// targets on the local FileSystem","Watch for makeQualified() calls that stamp hdfs:// (the default FS) onto paths later used as symlink targets"],"tags":["hadoop","local-filesystem","symlink","invalid-argument"],"backgroundTag":"filesystem-scheme-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}