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

Error "Symlinks not supported - please remove symlink before upgrading to this version of HDFS" thrown in apache/hadoop.

Source

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

        counter.increment();
      }
      final INodeDirectory dir = new INodeDirectory(inodeId, localName,
          permissions, modificationTime);
      if (nsQuota >= 0 || dsQuota >= 0) {
        dir.addDirectoryWithQuotaFeature(new DirectoryWithQuotaFeature.Builder().
            nameSpaceQuota(nsQuota).storageSpaceQuota(dsQuota).build());
      }
      if (withSnapshot) {
        dir.addSnapshotFeature(null);
      }
      if (snapshottable) {
        dir.addSnapshottableFeature();
      }
      return dir;
    } else if (numBlocks == -2) {
      //symlink
      if (!FileSystem.areSymlinksEnabled()) {
        throw new IOException("Symlinks not supported - please remove symlink before upgrading to this version of HDFS");
      }

      final String symlink = Text.readString(in);
      final PermissionStatus permissions = PermissionStatus.read(in);
      if (counter != null) {
        counter.increment();
      }
      return new INodeSymlink(inodeId, localName, permissions,
          modificationTime, atime, symlink);
    } else if (numBlocks == -3) {
      //reference
      // Intentionally do not increment counter, because it is too difficult at
      // this point to assess whether or not this is a reference that counts
      // toward quota.
      
      final boolean isWithName = in.readBoolean();
      // lastSnapshotId for WithName node, dstSnapshotId for DstReference node
      int snapshotId = in.readInt();

View on GitHub (pinned to 2add963021)

Solutions

1. Remove symlinks from the namespace before upgrading to an HDFS version that dropped symlink support.

When it happens

Trigger: Loading an old fsimage that contains symlinks, which this HDFS version no longer supports loading.

Common situations: See trigger scenarios.

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