apache/hadoop · error · UnsupportedOperationException

Symlinks not supported

Error message

Symlinks not supported

What it means

createSymlink first calls FileSystem.areSymlinksEnabled(), which reads the JVM-wide system property fs.FileSystem.symlinks.disabled. When that property is true (set to protect file systems that cannot honor symlinks), every symlink creation is refused with UnsupportedOperationException before the namespace is even consulted.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java:2461

      }
      logAuditEvent(true, operationName, src, null, status);
    } catch (AccessControlException e) {
      logAuditEvent(false, operationName, src);
      throw e;
    }
    assert(r != null);
    return r.getResult();
  }

  /**
   * Create a symbolic link.
   */
  void createSymlink(String target, String link,
      PermissionStatus dirPerms, boolean createParent, boolean logRetryCache)
      throws IOException {
    final String operationName = "createSymlink";
    if (!FileSystem.areSymlinksEnabled()) {
      throw new UnsupportedOperationException("Symlinks not supported");
    }
    FileStatus auditStat = null;
    checkOperation(OperationCategory.WRITE);
    FSPermissionChecker.setOperationType(operationName);
    try {
      writeLock(RwLockMode.FS);
      try {
        checkOperation(OperationCategory.WRITE);
        checkNameNodeSafeMode("Cannot create symlink " + link);
        auditStat = FSDirSymlinkOp.createSymlinkInt(this, target, link,
            dirPerms, createParent, logRetryCache);
      } finally {
        writeUnlock(RwLockMode.FS, operationName,
            getLockReportInfoSupplier(link, target, auditStat));
      }
    } catch (AccessControlException e) {
      logAuditEvent(false, operationName, link, target, null);
      throw e;

View on GitHub (pinned to 2add963021)

Solutions

1. Remove -Dfs.FileSystem.symlinks.disabled=true from the client JVM (or set it to false, or clear it before first FileSystem use)
2. If the flag must remain for other file systems, run the symlink-creating job in its own JVM/container without it
3. Where the flag is mandatory, avoid symlinks on that deployment: copy files or use manifest-based indirection

Example fix

# before
java -Dfs.FileSystem.symlinks.disabled=true MyJob   # createSymlink -> UnsupportedOperationException
# after
java MyJob                                       # property unset, symlink creation allowed

if (!FileSystem.areSymlinksEnabled()) {
  throw new IllegalStateException("Symlinks disabled in this JVM (fs.FileSystem.symlinks.disabled=true)");
}

catch (UnsupportedOperationException e) { if ("Symlinks not supported".equals(e.getMessage())) fallbackToCopy(); else throw e; }

When it happens

Trigger: The client JVM runs with -Dfs.FileSystem.symlinks.disabled=true (or calls System.setProperty before FileSystem class initialization) and then invokes FileSystem.createSymlink / DistributedFileSystem.createSymlink or FileContext.createSymlink on HDFS.

Common situations: Shared YARN/MapReduce containers where the framework sets the flag globally for incompatible file systems and it leaks into HDFS clients; distcp or Hive flows that materialize symlinks; cluster hardening scripts applying the flag everywhere.

Related errors

• Operation not supported
• ACLs are not supported on symlinks
• XAttrs are not supported on symlinks
• Storage policy are not supported on symlinks
• Symlinks not supported

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