apache/hadoop · error · IOException

Unable to create symlink to non-local file system: " + targe

Error message

Unable to create symlink to non-local file system: " + target.toString()

What it means

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.

Source

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

        : Optional.empty();
    return new LocalFileSystemPathHandle(p.toString(), mtime);
  }

  @Override
  public boolean supportsSymlinks() {
    return true;
  }

  @SuppressWarnings("deprecation")
  @Override
  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

View on GitHub (pinned to 2add963021)

Solutions

1. Pass an unqualified or file:// target: createSymlink(new Path("/local/data"), link, true)
2. Use a manifest/reference file listing the hdfs:// location instead of a symlink
3. Pre-check the scheme and reject non-local targets with your own clear error before calling createSymlink

Example fix

// before
rawFs.createSymlink(new Path("hdfs://nn/data"), link, true); // IOException

// after
rawFs.createSymlink(new Path("/local/data"), link, true); // local target

String scheme = target.toUri().getScheme();
if (scheme != null && !"file".equals(scheme)) {
  throw new IOException("Refusing non-local symlink target: " + target);
}
fs.createSymlink(target, link, true);

try {
  fs.createSymlink(target, link, true);
} catch (IOException e) {
  // message starts with "Unable to create symlink to non-local file system"
  throw new IllegalArgumentException("Symlink target must be local: " + target, e);
}

When it happens

Trigger: 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/...".

Common situations: 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.

Related errors

• PathHandle only available for files
• Symlinks not supported
• Error " + result + " creating symlink " + link + " to " + ta
• Checksum file not a length multiple of checksum size in {} a
• Checksum error: {} at {}

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