apache/hadoop · error · IOException

Symlinks not supported - please remove symlink before upgrad

Error message

Symlinks not supported - please remove symlink before upgrading to this version of HDFS

What it means

Replay of OP_SYMLINK while FileSystem.areSymlinksEnabled() returns false. In this Hadoop line symlinks are disabled by default (FileSystem.java:4631, HADOOP-10020 and HADOOP-10052), so any symlink creation left in the edit log aborts replay. The message instructs you to remove symlinks on the old release before upgrading.

Source

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

          setQuotaByStorageTypeOp.src, logVersion);
      final INodesInPath iip = fsDir.getINodesInPath(src, DirOp.WRITE);
      FSDirAttrOp.unprotectedSetQuota(fsDir, iip,
          HdfsConstants.QUOTA_DONT_SET, setQuotaByStorageTypeOp.dsQuota,
          setQuotaByStorageTypeOp.type);
      break;
    }
    case OP_TIMES: {
      TimesOp timesOp = (TimesOp)op;
      final String src = renameReservedPathsOnUpgrade(
          timesOp.path, logVersion);
      final INodesInPath iip = fsDir.getINodesInPath(src, DirOp.WRITE);
      FSDirAttrOp.unprotectedSetTimes(fsDir, iip,
          timesOp.mtime, timesOp.atime, true);
      break;
    }
    case OP_SYMLINK: {
      if (!FileSystem.areSymlinksEnabled()) {
        throw new IOException("Symlinks not supported - please remove symlink before upgrading to this version of HDFS");
      }
      SymlinkOp symlinkOp = (SymlinkOp)op;
      inodeId = getAndUpdateLastInodeId(symlinkOp.inodeId, logVersion,
          lastInodeId);
      final String path = renameReservedPathsOnUpgrade(symlinkOp.path,
          logVersion);
      final INodesInPath iip = fsDir.getINodesInPath(path, DirOp.WRITE_LINK);
      FSDirSymlinkOp.unprotectedAddSymlink(fsDir, iip.getExistingINodes(),
          iip.getLastLocalName(), inodeId, symlinkOp.value, symlinkOp.mtime,
          symlinkOp.atime, symlinkOp.permissionStatus);
      
      if (toAddRetryCache) {
        fsNamesys.addCacheEntry(symlinkOp.rpcClientId, symlinkOp.rpcCallId);
      }
      break;
    }
    case OP_RENAME: {
      RenameOp renameOp = (RenameOp)op;

View on GitHub (pinned to 2add963021)

Solutions

Go back to the old release, delete the symlink files, and force a checkpoint (saveNamespace) so OP_SYMLINK records leave the active edit logs, then redo the upgrade
Take a clean checkpoint immediately before any upgrade so the replayed edit window is minimal
If the symlinks must survive, upgrade to a Hadoop version with symlink support enabled instead

Example fix

# before: upgrade attempted with symlink edits still in the log
# OP_SYMLINK replay throws, NameNode will not start

# after: on the OLD release first
hdfs dfs -find / -type l > /tmp/symlinks.txt   # locate and remove them
hdfs dfsadmin -saveNamespace                    # checkpoint symlinks out of edits
# shut down cleanly, then run the upgrade

Defensive patterns

Strategy: validation

Validate before calling

# before upgrading: no OP_SYMLINK may remain in the active edits
hdfs oev -i $(ls -t edits_* edits_inprogress_* 2>/dev/null | head -1) -o /tmp/edits.xml -p xml
grep -c 'SYMLINK' /tmp/edits.xml   # count > 0: remove symlinks and checkpoint on the old release first

Try / catch

try {
  loader.loadFSEdits(storage, 0);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Symlinks not supported")) {
    // abort the upgrade: go back to the old release, remove symlinks,
    // checkpoint (saveNamespace), then retry
  }
  throw e;
}

Prevention

Take a checkpoint immediately before every upgrade so old feature ops leave the edits
Do not create symlinks on versions where the feature is disabled or incomplete
Read the target release's upgrade notes for feature-removal notices

When it happens

Trigger: Upgrading into a symlink-disabled build while active edit logs still hold un-checkpointed OP_SYMLINK records; NameNode restart after symlink ops were written by an older build that allowed them.

Common situations: Cluster created symlinks under an older version, then upgraded to a version where support is disabled; no checkpoint taken before the upgrade, so old symlink ops remain in the edits to replay.

Related errors

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