apache/hadoop · error · IOException

File system does not support symlinks

Error message

File system does not support symlinks

What it means

AbstractFileSystem.createSymlink has no base implementation: it throws IOException 'File system does not support symlinks', and only concrete filesystems that opt in (LocalFs, HDFS's Hdfs AFS, pass-through filters) override it. Calling fc.createSymlink(target, link, createParent) on a filesystem without the override (object stores like S3A/ABFS/GCS, ftp, http) always fails. The supportsSymlinks() probe and the fs.capability.paths.symlinks path capability advertise whether links exist.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/AbstractFileSystem.java:919

   * @return true if filesystem supports symlinks
   */
  public boolean supportsSymlinks() {
    return false;
  }
  
  /**
   * The specification of this method matches that of  
   * {@link FileContext#createSymlink(Path, Path, boolean)};
   *
   * @param target target.
   * @param link link.
   * @param createParent create parent.
   * @throws IOException raised on errors performing I/O.
   * @throws UnresolvedLinkException unresolved link exception.
   */
  public void createSymlink(final Path target, final Path link,
      final boolean createParent) throws IOException, UnresolvedLinkException {
    throw new IOException("File system does not support symlinks");    
  }

  /**
   * Partially resolves the path. This is used during symlink resolution in
   * {@link FSLinkResolver}, and differs from the similarly named method
   * {@link FileContext#getLinkTarget(Path)}.
   * @param f the path.
   * @return target path.
   * @throws IOException subclass implementations may throw IOException 
   */
  public Path getLinkTarget(final Path f) throws IOException {
    throw new AssertionError("Implementation Error: " + getClass()
        + " that threw an UnresolvedLinkException, causing this method to be"
        + " called, needs to override this method.");
  }
    
  /**
   * The specification of this method matches that of

View on GitHub (pinned to 2add963021)

Solutions

1. Probe first: fc.supportsSymlinks() or fc.hasPathCapability(link, CommonPathCapabilities.FS_SYMLINKS), and skip link creation when unsupported
2. Use a filesystem that implements symlinks (file:// or HDFS) for the paths that need links
3. Replace symlinks with a pointer/manifest file convention on stores without link support

Example fix

// before
fc.createSymlink(target, link, true); // on s3a:// -> IOException

// after
if (fc.hasPathCapability(link, CommonPathCapabilities.FS_SYMLINKS)) {
  fc.createSymlink(target, link, true);
} else {
  writePointerFile(link, target); // manifest convention
}

boolean canCreateLinks(Path p) throws IOException {
  return fc.hasPathCapability(p, CommonPathCapabilities.FS_SYMLINKS);
}

catch (IOException e) { if (e.getMessage().equals("File system does not support symlinks")) { /* fall back to pointer/manifest file */ } else throw e; }

When it happens

Trigger: fc.createSymlink(target, link, true) on any AFS that does not override createSymlink (object-store schemes, ftp://, http://); jobs written against file:// or HDFS run unchanged against an object-store defaultFS.

Common situations: Porting pipelines from HDFS to S3-compatible storage while keeping 'current -> version' pointer links; unit tests on LocalFs passing but production on s3a:// failing; configuration switching fs.defaultFS to an object store without auditing link usage.

Related errors

• Cannot rename symlink {src} to its target {dst}
• {getClass().getSimpleName()} doesn't support modifyAclEntrie
• {getClass().getSimpleName()} doesn't support removeAclEntrie
• {getClass().getSimpleName()} doesn't support removeDefaultAc
• {} doesn't support removeAcl

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