{"record":{"id":"bc5d83ef73335c96","repo":"apache/hadoop","slug":"symlinks-not-supported-bc5d83","errorCode":null,"errorMessage":"Symlinks not supported","messagePattern":"Symlinks not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java","lineNumber":1266,"sourceCode":"    }\n    final Path p = stat.getPath();\n    final Optional<Long> mtime = !data.allowChange()\n        ? Optional.of(stat.getModificationTime())\n        : Optional.empty();\n    return new LocalFileSystemPathHandle(p.toString(), mtime);\n  }\n\n  @Override\n  public boolean supportsSymlinks() {\n    return true;\n  }\n\n  @SuppressWarnings(\"deprecation\")\n  @Override\n  public void createSymlink(Path target, Path link, boolean createParent)\n      throws IOException {\n    if (!FileSystem.areSymlinksEnabled()) {\n      throw new UnsupportedOperationException(\"Symlinks not supported\");\n    }\n    final String targetScheme = target.toUri().getScheme();\n    if (targetScheme != null && !\"file\".equals(targetScheme)) {\n      throw new IOException(\"Unable to create symlink to non-local file \"+\n                            \"system: \"+target.toString());\n    }\n    if (createParent) {\n      mkdirs(link.getParent());\n    }\n\n    // NB: Use createSymbolicLink in java.nio.file.Path once available\n    int result = FileUtil.symLink(target.toString(),\n        makeAbsolute(link).toString());\n    if (result != 0) {\n      throw new IOException(\"Error \" + result + \" creating symlink \" +\n          link + \" to \" + target);\n    }\n  }","sourceCodeStart":1248,"sourceCodeEnd":1284,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RawLocalFileSystem.java#L1248-L1284","documentation":"Thrown by RawLocalFileSystem.createSymlink when FileSystem.areSymlinksEnabled() returns false. Symlinks in Hadoop FileSystem are disabled globally by default (symlinksEnabled = false, see HADOOP-10020/HADOOP-10052) because supporting them across all FileSystems broke path resolution; the enable method is @VisibleForTesting. In any production JVM this throws UnsupportedOperationException on the first call.","triggerScenarios":"Calling FileSystem.createSymlink(target, link, createParent) or FileContext.createSymlink on RawLocalFileSystem without a prior test-only FileSystem.enableSymlinks() call in the same JVM.","commonSituations":"Running old MapReduce/user code written before symlinks were disabled (Hadoop 2.x era); unit tests that forgot the FileSystem.enableSymlinks() setup; code copied from test classes into production jobs.","solutions":["For local paths, bypass Hadoop and use java.nio.file.Files.createSymbolicLink directly","In tests, call FileSystem.enableSymlinks() once in @BeforeClass/@BeforeAll","Replace symlink usage with hard links (FileUtil.hardLink), copies, or manifest files referencing alternate locations"],"exampleFix":"// before\nrawFs.createSymlink(target, link, true); // UnsupportedOperationException by default\n\n// after\njava.nio.file.Files.createSymbolicLink(\n    new java.io.File(link.toUri().getPath()).toPath(),\n    new java.io.File(target.toUri().getPath()).toPath());","handlingStrategy":"validation","validationCode":"if (!FileSystem.areSymlinksEnabled()) {\n  // use java.nio for local paths; do not call fs.createSymlink\n  java.nio.file.Files.createSymbolicLink(\n      java.nio.file.Paths.get(link.toUri().getPath()),\n      java.nio.file.Paths.get(target.toUri().getPath()));\n} else {\n  fs.createSymlink(target, link, true);\n}","typeGuard":null,"tryCatchPattern":"try {\n  fs.createSymlink(target, link, true);\n} catch (UnsupportedOperationException e) {\n  // symlinks globally disabled (HADOOP-10020); fall back to NIO for local paths\n  java.nio.file.Files.createSymbolicLink(\n      java.nio.file.Paths.get(link.toUri().getPath()),\n      java.nio.file.Paths.get(target.toUri().getPath()));\n}","preventionTips":["Do not use Hadoop symlink APIs in production code; they are disabled by default","In tests, call FileSystem.enableSymlinks() in the setup phase, and never let that setup leak into production paths"],"tags":["hadoop","local-filesystem","symlink","unsupported-operation"],"backgroundTag":"symlink-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}