{"record":{"id":"0974f2c5493ea472","repo":"apache/hadoop","slug":"symlinks-not-supported-please-remove-symlink-bef","errorCode":null,"errorMessage":"Symlinks not supported - please remove symlink before upgrading to this version of HDFS","messagePattern":"Symlinks not supported - please remove symlink before upgrading to this version of HDFS","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSEditLogLoader.java","lineNumber":720,"sourceCode":"          setQuotaByStorageTypeOp.src, logVersion);\n      final INodesInPath iip = fsDir.getINodesInPath(src, DirOp.WRITE);\n      FSDirAttrOp.unprotectedSetQuota(fsDir, iip,\n          HdfsConstants.QUOTA_DONT_SET, setQuotaByStorageTypeOp.dsQuota,\n          setQuotaByStorageTypeOp.type);\n      break;\n    }\n    case OP_TIMES: {\n      TimesOp timesOp = (TimesOp)op;\n      final String src = renameReservedPathsOnUpgrade(\n          timesOp.path, logVersion);\n      final INodesInPath iip = fsDir.getINodesInPath(src, DirOp.WRITE);\n      FSDirAttrOp.unprotectedSetTimes(fsDir, iip,\n          timesOp.mtime, timesOp.atime, true);\n      break;\n    }\n    case OP_SYMLINK: {\n      if (!FileSystem.areSymlinksEnabled()) {\n        throw new IOException(\"Symlinks not supported - please remove symlink before upgrading to this version of HDFS\");\n      }\n      SymlinkOp symlinkOp = (SymlinkOp)op;\n      inodeId = getAndUpdateLastInodeId(symlinkOp.inodeId, logVersion,\n          lastInodeId);\n      final String path = renameReservedPathsOnUpgrade(symlinkOp.path,\n          logVersion);\n      final INodesInPath iip = fsDir.getINodesInPath(path, DirOp.WRITE_LINK);\n      FSDirSymlinkOp.unprotectedAddSymlink(fsDir, iip.getExistingINodes(),\n          iip.getLastLocalName(), inodeId, symlinkOp.value, symlinkOp.mtime,\n          symlinkOp.atime, symlinkOp.permissionStatus);\n      \n      if (toAddRetryCache) {\n        fsNamesys.addCacheEntry(symlinkOp.rpcClientId, symlinkOp.rpcCallId);\n      }\n      break;\n    }\n    case OP_RENAME: {\n      RenameOp renameOp = (RenameOp)op;","sourceCodeStart":702,"sourceCodeEnd":738,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSEditLogLoader.java#L702-L738","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before: upgrade attempted with symlink edits still in the log\n# OP_SYMLINK replay throws, NameNode will not start\n\n# after: on the OLD release first\nhdfs dfs -find / -type l > /tmp/symlinks.txt   # locate and remove them\nhdfs dfsadmin -saveNamespace                    # checkpoint symlinks out of edits\n# shut down cleanly, then run the upgrade","handlingStrategy":"validation","validationCode":"# before upgrading: no OP_SYMLINK may remain in the active edits\nhdfs oev -i $(ls -t edits_* edits_inprogress_* 2>/dev/null | head -1) -o /tmp/edits.xml -p xml\ngrep -c 'SYMLINK' /tmp/edits.xml   # count > 0: remove symlinks and checkpoint on the old release first","typeGuard":null,"tryCatchPattern":"try {\n  loader.loadFSEdits(storage, 0);\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Symlinks not supported\")) {\n    // abort the upgrade: go back to the old release, remove symlinks,\n    // checkpoint (saveNamespace), then retry\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["hdfs","namenode","symlink","upgrade","edit-log","op-symlink"],"backgroundTag":"unsupported-feature-on-upgrade","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}