apache/hadoop · error · UnsupportedOperationException

Filesystem does not support symlinks!

Error message

Filesystem does not support symlinks!

What it means

FileSystem.createSymlink(target, link, createParent) is optional; the base class throws UnsupportedOperationException with the fixed message 'Filesystem does not support symlinks!'. Implementations that override it: RawLocalFileSystem/LocalFileSystem (via FileUtil.symlink), WebHdfsFileSystem, ViewFs/ViewDistributedFileSystem, and — since Hadoop 3.4 (HDFS-347) — DistributedFileSystem. Everything else (S3A, ABFS, GCS, HarFileSystem, pre-3.4 HDFS clients) throws.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java:2913

   * @param target target path.
   * @param link link.
   * @param createParent create parent.
   * @throws AccessControlException if access is denied.
   * @throws FileAlreadyExistsException when the path does not exist.
   * @throws FileNotFoundException when the path does not exist.
   * @throws ParentNotDirectoryException if the parent path of dest is not
   *                                     a directory.
   * @throws UnsupportedFileSystemException if there was no known implementation
   *                                        for the scheme.
   * @throws IOException raised on errors performing I/O.
   */
  public void createSymlink(final Path target, final Path link,
      final boolean createParent) throws AccessControlException,
      FileAlreadyExistsException, FileNotFoundException,
      ParentNotDirectoryException, UnsupportedFileSystemException,
      IOException {
    // Supporting filesystems should override this method
    throw new UnsupportedOperationException(
        "Filesystem does not support symlinks!");
  }

  /**
   * See {@link FileContext#getFileLinkStatus(Path)}.
   *
   * @param f the path.
   * @throws AccessControlException if access is denied.
   * @throws FileNotFoundException when the path does not exist.
   * @throws IOException raised on errors performing I/O.
   * @throws UnsupportedFileSystemException if there was no known implementation
   *                                        for the scheme.
   * @return file status
   */
  public FileStatus getFileLinkStatus(final Path f)
      throws AccessControlException, FileNotFoundException,
      UnsupportedFileSystemException, IOException {
    // Supporting filesystems should override this method

View on GitHub (pinned to 2add963021)

Solutions

  1. Probe first: fs.hasPathCapability(linkPath, CommonPathCapabilities.FS_SYMLINKS), or check fs instanceof for a known-supporting class
  2. On HDFS, upgrade to Hadoop 3.4+ where createSymlink is implemented (HDFS-347)
  3. On object stores, replace links with reference/manifest files or client-side indirection (ViewFs mount tables)
  4. Catch UnsupportedOperationException and fall back to copying the target

Example fix

// before
fs.createSymlink(new Path("/data/current"), new Path("/data/latest"), true);
// UnsupportedOperationException: Filesystem does not support symlinks!

// after
if (fs.hasPathCapability(linkPath, CommonPathCapabilities.FS_SYMLINKS)) {
  fs.createSymlink(target, linkPath, true);
} else {
  writeManifestFile(linkPath, target); // store indirection instead
}
Defensive patterns

Strategy: try-catch

Validate before calling

import org.apache.hadoop.fs.CommonPathCapabilities;

if (fs.hasPathCapability(linkPath, CommonPathCapabilities.FS_SYMLINKS)) {
  fs.createSymlink(target, linkPath, true);
} else {
  // store cannot hold links: use indirection
}

Type guard

static boolean supportsSymlinks(FileSystem fs) {
  return fs instanceof LocalFileSystem
      || fs instanceof WebHdfsFileSystem
      || fs instanceof DistributedFileSystem; // 3.4+
}

Try / catch

try {
  fs.createSymlink(target, link, createParent);
} catch (UnsupportedOperationException e) {
  // 'Filesystem does not support symlinks!' — fall back to copy or manifest indirection
}

Prevention

When it happens

Trigger: Calling fs.createSymlink(...) on s3a://, abfs://, gs://, har:// paths; on HDFS with a Hadoop 3.3-or-older client where DistributedFileSystem did not yet override the method; via FileContext.createSymlink on any non-supporting store.

Common situations: Pipelines ported from file:// (where symlinks work) to object stores; frameworks (e.g., FileContext-based apps, symlink-aware test harnesses) assuming POSIX link semantics; version skew: same code works on a Hadoop 3.4+ cluster but throws on an older one.

Related errors

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