{"record":{"id":"65f2f74493aebe9f","repo":"apache/hadoop","slug":"filesystem-does-not-support-symlinks","errorCode":null,"errorMessage":"Filesystem does not support symlinks!","messagePattern":"Filesystem does not support symlinks!","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java","lineNumber":2913,"sourceCode":"   * @param target target path.\n   * @param link link.\n   * @param createParent create parent.\n   * @throws AccessControlException if access is denied.\n   * @throws FileAlreadyExistsException when the path does not exist.\n   * @throws FileNotFoundException when the path does not exist.\n   * @throws ParentNotDirectoryException if the parent path of dest is not\n   *                                     a directory.\n   * @throws UnsupportedFileSystemException if there was no known implementation\n   *                                        for the scheme.\n   * @throws IOException raised on errors performing I/O.\n   */\n  public void createSymlink(final Path target, final Path link,\n      final boolean createParent) throws AccessControlException,\n      FileAlreadyExistsException, FileNotFoundException,\n      ParentNotDirectoryException, UnsupportedFileSystemException,\n      IOException {\n    // Supporting filesystems should override this method\n    throw new UnsupportedOperationException(\n        \"Filesystem does not support symlinks!\");\n  }\n\n  /**\n   * See {@link FileContext#getFileLinkStatus(Path)}.\n   *\n   * @param f the path.\n   * @throws AccessControlException if access is denied.\n   * @throws FileNotFoundException when the path does not exist.\n   * @throws IOException raised on errors performing I/O.\n   * @throws UnsupportedFileSystemException if there was no known implementation\n   *                                        for the scheme.\n   * @return file status\n   */\n  public FileStatus getFileLinkStatus(final Path f)\n      throws AccessControlException, FileNotFoundException,\n      UnsupportedFileSystemException, IOException {\n    // Supporting filesystems should override this method","sourceCodeStart":2895,"sourceCodeEnd":2931,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java#L2895-L2931","documentation":"FileSystem.createSymlink(target, link, createParent) is optional; the base class throws UnsupportedOperationException with the fixed message 'Filesystem does not support symlinks!'. Implementations that override it: RawLocalFileSystem/LocalFileSystem (via FileUtil.symlink), WebHdfsFileSystem, ViewFs/ViewDistributedFileSystem, and — since Hadoop 3.4 (HDFS-347) — DistributedFileSystem. Everything else (S3A, ABFS, GCS, HarFileSystem, pre-3.4 HDFS clients) throws.","triggerScenarios":"Calling fs.createSymlink(...) on s3a://, abfs://, gs://, har:// paths; on HDFS with a Hadoop 3.3-or-older client where DistributedFileSystem did not yet override the method; via FileContext.createSymlink on any non-supporting store.","commonSituations":"Pipelines ported from file:// (where symlinks work) to object stores; frameworks (e.g., FileContext-based apps, symlink-aware test harnesses) assuming POSIX link semantics; version skew: same code works on a Hadoop 3.4+ cluster but throws on an older one.","solutions":["Probe first: fs.hasPathCapability(linkPath, CommonPathCapabilities.FS_SYMLINKS), or check fs instanceof for a known-supporting class","On HDFS, upgrade to Hadoop 3.4+ where createSymlink is implemented (HDFS-347)","On object stores, replace links with reference/manifest files or client-side indirection (ViewFs mount tables)","Catch UnsupportedOperationException and fall back to copying the target"],"exampleFix":"// before\nfs.createSymlink(new Path(\"/data/current\"), new Path(\"/data/latest\"), true);\n// UnsupportedOperationException: Filesystem does not support symlinks!\n\n// after\nif (fs.hasPathCapability(linkPath, CommonPathCapabilities.FS_SYMLINKS)) {\n  fs.createSymlink(target, linkPath, true);\n} else {\n  writeManifestFile(linkPath, target); // store indirection instead\n}","handlingStrategy":"try-catch","validationCode":"import org.apache.hadoop.fs.CommonPathCapabilities;\n\nif (fs.hasPathCapability(linkPath, CommonPathCapabilities.FS_SYMLINKS)) {\n  fs.createSymlink(target, linkPath, true);\n} else {\n  // store cannot hold links: use indirection\n}","typeGuard":"static boolean supportsSymlinks(FileSystem fs) {\n  return fs instanceof LocalFileSystem\n      || fs instanceof WebHdfsFileSystem\n      || fs instanceof DistributedFileSystem; // 3.4+\n}","tryCatchPattern":"try {\n  fs.createSymlink(target, link, createParent);\n} catch (UnsupportedOperationException e) {\n  // 'Filesystem does not support symlinks!' — fall back to copy or manifest indirection\n}","preventionTips":["Never assume POSIX link semantics on object stores; design an indirection layer from the start","On HDFS, deploy a Hadoop 3.4+ client before shipping symlink features","Probe FS_SYMLINKS once per FileSystem instance and cache the result"],"tags":["hadoop","filesystem","symlink","unsupportedoperationexception","hdfs","object-store"],"backgroundTag":"filesystem-symlink-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}