{"record":{"id":"bd0784ed43b0c391","repo":"apache/hadoop","slug":"symlinks-not-supported-bd0784","errorCode":null,"errorMessage":"Symlinks not supported","messagePattern":"Symlinks not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java","lineNumber":1960,"sourceCode":"\n  /**\n   * Synchronize client metadata state with Active NameNode.\n   * <p>\n   * In HA the client synchronizes its state with the Active NameNode\n   * in order to guarantee subsequent read consistency from Observer Nodes.\n   * @throws IOException\n   */\n  @Override\n  public void msync() throws IOException {\n    dfs.msync();\n  }\n\n  @SuppressWarnings(\"deprecation\")\n  @Override\n  public void createSymlink(final Path target, final Path link,\n      final boolean createParent) throws IOException {\n    if (!FileSystem.areSymlinksEnabled()) {\n      throw new UnsupportedOperationException(\"Symlinks not supported\");\n    }\n    statistics.incrementWriteOps(1);\n    storageStatistics.incrementOpCounter(OpType.CREATE_SYM_LINK);\n    final Path absF = fixRelativePart(link);\n    new FileSystemLinkResolver<Void>() {\n      @Override\n      public Void doCall(final Path p) throws IOException {\n        dfs.createSymlink(target.toString(), getPathName(p), createParent);\n        return null;\n      }\n      @Override\n      public Void next(final FileSystem fs, final Path p) throws IOException {\n        fs.createSymlink(target, p, createParent);\n        return null;\n      }\n    }.resolve(this, absF);\n  }\n","sourceCodeStart":1942,"sourceCodeEnd":1978,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java#L1942-L1978","documentation":"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.","triggerScenarios":"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).","commonSituations":"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()).","solutions":["Avoid HDFS symlinks; write the target path into a manifest/_link file or use fully-qualified paths instead.","In tests, call FileSystem.enableSymlinks() once before symlink operations.","Guard the call: if (fs.supportsSymlinks() && FileSystem.areSymlinksEnabled()) else use an alternative indirection.","Upgrade to a Hadoop version where symlink support is enabled and stable, after verifying the cluster supports them."],"exampleFix":"// before\nfs.createSymlink(target, link, true); // UnsupportedOperationException by default\n\n// after\nif (fs instanceof DistributedFileSystem\n    && FileSystem.areSymlinksEnabled()) {\n  fs.createSymlink(target, link, true);\n} else {\n  // fall back to writing a pointer file\n  try (FSDataOutputStream out = fs.create(linkPointerPath, true)) {\n    out.writeUTF(target.toString());\n  }\n}","handlingStrategy":"validation","validationCode":"if (!FileSystem.areSymlinksEnabled() || !fs.supportsSymlinks()) {\n  // do not call createSymlink; use an alternative indirection\n}","typeGuard":null,"tryCatchPattern":"try {\n  fs.createSymlink(target, link, true);\n} catch (UnsupportedOperationException e) {\n  // symlinks disabled in this JVM/version: fall back to pointer files\n}","preventionTips":["Check the capability (areSymlinksEnabled + supportsSymlinks) once at startup, not per call.","In tests, call FileSystem.enableSymlinks() in @BeforeClass when symlink behavior is under test.","Prefer manifest/pointer-file indirection over HDFS symlinks for portable pipelines."],"tags":["hdfs","symlink","unsupported-operation","feature-disabled","distributed-filesystem"],"backgroundTag":"symlinks-disabled","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}