apache/hadoop · error · UnsupportedOperationException

Symlinks not supported

Error message

Symlinks not supported

What it means

createSymlink checks the static global flag FileSystem.areSymlinksEnabled() before doing anything and throws UnsupportedOperationException when symlinks are disabled. In this codebase the flag defaults to false (comment cites HADOOP-10020/HADOOP-10052) and is flipped only through the @VisibleForTesting FileSystem.enableSymlinks(), so by default every symlink creation through DistributedFileSystem fails.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java:1960

  /**
   * Synchronize client metadata state with Active NameNode.
   * <p>
   * In HA the client synchronizes its state with the Active NameNode
   * in order to guarantee subsequent read consistency from Observer Nodes.
   * @throws IOException
   */
  @Override
  public void msync() throws IOException {
    dfs.msync();
  }

  @SuppressWarnings("deprecation")
  @Override
  public void createSymlink(final Path target, final Path link,
      final boolean createParent) throws IOException {
    if (!FileSystem.areSymlinksEnabled()) {
      throw new UnsupportedOperationException("Symlinks not supported");
    }
    statistics.incrementWriteOps(1);
    storageStatistics.incrementOpCounter(OpType.CREATE_SYM_LINK);
    final Path absF = fixRelativePart(link);
    new FileSystemLinkResolver<Void>() {
      @Override
      public Void doCall(final Path p) throws IOException {
        dfs.createSymlink(target.toString(), getPathName(p), createParent);
        return null;
      }
      @Override
      public Void next(final FileSystem fs, final Path p) throws IOException {
        fs.createSymlink(target, p, createParent);
        return null;
      }
    }.resolve(this, absF);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Avoid HDFS symlinks; write the target path into a manifest/_link file or use fully-qualified paths instead.
2. In tests, call FileSystem.enableSymlinks() once before symlink operations.
3. Guard the call: if (fs.supportsSymlinks() && FileSystem.areSymlinksEnabled()) else use an alternative indirection.
4. Upgrade to a Hadoop version where symlink support is enabled and stable, after verifying the cluster supports them.

Example fix

// before
fs.createSymlink(target, link, true); // UnsupportedOperationException by default

// after
if (fs instanceof DistributedFileSystem
    && FileSystem.areSymlinksEnabled()) {
  fs.createSymlink(target, link, true);
} else {
  // fall back to writing a pointer file
  try (FSDataOutputStream out = fs.create(linkPointerPath, true)) {
    out.writeUTF(target.toString());
  }
}

if (!FileSystem.areSymlinksEnabled() || !fs.supportsSymlinks()) {
  // do not call createSymlink; use an alternative indirection
}

try {
  fs.createSymlink(target, link, true);
} catch (UnsupportedOperationException e) {
  // symlinks disabled in this JVM/version: fall back to pointer files
}

When it happens

Trigger: Calling DistributedFileSystem.createSymlink(target, link, createParent) in a JVM where FileSystem.enableSymlinks() was never invoked (i.e., any normal production or test run in this version).

Common situations: Code ported from Hadoop versions where symlinks were enabled by default; test code that forgets to call FileSystem.enableSymlinks() in @BeforeClass; tools that unconditionally create symlinks on HDFS without a capability check (FileSystem.supportsSymlinks() && areSymlinksEnabled()).

Related errors

• Cannot perform snapshot operations on a symlink to a non-Dis
• Operation not supported
• Symlinks not supported
• ACLs are not supported on symlinks
• XAttrs are not supported on symlinks

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