{"record":{"id":"fb4ead4e4573b1bb","repo":"apache/hadoop","slug":"symlinks-not-supported-fb4ead","errorCode":null,"errorMessage":"Symlinks not supported","messagePattern":"Symlinks not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java","lineNumber":2461,"sourceCode":"      }\n      logAuditEvent(true, operationName, src, null, status);\n    } catch (AccessControlException e) {\n      logAuditEvent(false, operationName, src);\n      throw e;\n    }\n    assert(r != null);\n    return r.getResult();\n  }\n\n  /**\n   * Create a symbolic link.\n   */\n  void createSymlink(String target, String link,\n      PermissionStatus dirPerms, boolean createParent, boolean logRetryCache)\n      throws IOException {\n    final String operationName = \"createSymlink\";\n    if (!FileSystem.areSymlinksEnabled()) {\n      throw new UnsupportedOperationException(\"Symlinks not supported\");\n    }\n    FileStatus auditStat = null;\n    checkOperation(OperationCategory.WRITE);\n    FSPermissionChecker.setOperationType(operationName);\n    try {\n      writeLock(RwLockMode.FS);\n      try {\n        checkOperation(OperationCategory.WRITE);\n        checkNameNodeSafeMode(\"Cannot create symlink \" + link);\n        auditStat = FSDirSymlinkOp.createSymlinkInt(this, target, link,\n            dirPerms, createParent, logRetryCache);\n      } finally {\n        writeUnlock(RwLockMode.FS, operationName,\n            getLockReportInfoSupplier(link, target, auditStat));\n      }\n    } catch (AccessControlException e) {\n      logAuditEvent(false, operationName, link, target, null);\n      throw e;","sourceCodeStart":2443,"sourceCodeEnd":2479,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java#L2443-L2479","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove -Dfs.FileSystem.symlinks.disabled=true from the client JVM (or set it to false, or clear it before first FileSystem use)","If the flag must remain for other file systems, run the symlink-creating job in its own JVM/container without it","Where the flag is mandatory, avoid symlinks on that deployment: copy files or use manifest-based indirection"],"exampleFix":"# before\njava -Dfs.FileSystem.symlinks.disabled=true MyJob   # createSymlink -> UnsupportedOperationException\n# after\njava MyJob                                       # property unset, symlink creation allowed","handlingStrategy":"validation","validationCode":"if (!FileSystem.areSymlinksEnabled()) {\n  throw new IllegalStateException(\"Symlinks disabled in this JVM (fs.FileSystem.symlinks.disabled=true)\");\n}","typeGuard":null,"tryCatchPattern":"catch (UnsupportedOperationException e) { if (\"Symlinks not supported\".equals(e.getMessage())) fallbackToCopy(); else throw e; }","preventionTips":["Audit container/JVM launch flags for fs.FileSystem.symlinks.disabled","Check areSymlinksEnabled() at app init and fail fast with a clear message"],"tags":["hdfs","symlink","system-property","unsupported-operation","client-jvm"],"backgroundTag":"feature-disabled-by-config","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}