{"record":{"id":"29be01997567d606","repo":"apache/hadoop","slug":"file-system-does-not-support-symlinks","errorCode":null,"errorMessage":"File system does not support symlinks","messagePattern":"File system does not support symlinks","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/AbstractFileSystem.java","lineNumber":919,"sourceCode":"   * @return true if filesystem supports symlinks\n   */\n  public boolean supportsSymlinks() {\n    return false;\n  }\n  \n  /**\n   * The specification of this method matches that of  \n   * {@link FileContext#createSymlink(Path, Path, boolean)};\n   *\n   * @param target target.\n   * @param link link.\n   * @param createParent create parent.\n   * @throws IOException raised on errors performing I/O.\n   * @throws UnresolvedLinkException unresolved link exception.\n   */\n  public void createSymlink(final Path target, final Path link,\n      final boolean createParent) throws IOException, UnresolvedLinkException {\n    throw new IOException(\"File system does not support symlinks\");    \n  }\n\n  /**\n   * Partially resolves the path. This is used during symlink resolution in\n   * {@link FSLinkResolver}, and differs from the similarly named method\n   * {@link FileContext#getLinkTarget(Path)}.\n   * @param f the path.\n   * @return target path.\n   * @throws IOException subclass implementations may throw IOException \n   */\n  public Path getLinkTarget(final Path f) throws IOException {\n    throw new AssertionError(\"Implementation Error: \" + getClass()\n        + \" that threw an UnresolvedLinkException, causing this method to be\"\n        + \" called, needs to override this method.\");\n  }\n    \n  /**\n   * The specification of this method matches that of","sourceCodeStart":901,"sourceCodeEnd":937,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/AbstractFileSystem.java#L901-L937","documentation":"AbstractFileSystem.createSymlink has no base implementation: it throws IOException 'File system does not support symlinks', and only concrete filesystems that opt in (LocalFs, HDFS's Hdfs AFS, pass-through filters) override it. Calling fc.createSymlink(target, link, createParent) on a filesystem without the override (object stores like S3A/ABFS/GCS, ftp, http) always fails. The supportsSymlinks() probe and the fs.capability.paths.symlinks path capability advertise whether links exist.","triggerScenarios":"fc.createSymlink(target, link, true) on any AFS that does not override createSymlink (object-store schemes, ftp://, http://); jobs written against file:// or HDFS run unchanged against an object-store defaultFS.","commonSituations":"Porting pipelines from HDFS to S3-compatible storage while keeping 'current -> version' pointer links; unit tests on LocalFs passing but production on s3a:// failing; configuration switching fs.defaultFS to an object store without auditing link usage.","solutions":["Probe first: fc.supportsSymlinks() or fc.hasPathCapability(link, CommonPathCapabilities.FS_SYMLINKS), and skip link creation when unsupported","Use a filesystem that implements symlinks (file:// or HDFS) for the paths that need links","Replace symlinks with a pointer/manifest file convention on stores without link support"],"exampleFix":"// before\nfc.createSymlink(target, link, true); // on s3a:// -> IOException\n\n// after\nif (fc.hasPathCapability(link, CommonPathCapabilities.FS_SYMLINKS)) {\n  fc.createSymlink(target, link, true);\n} else {\n  writePointerFile(link, target); // manifest convention\n}","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"boolean canCreateLinks(Path p) throws IOException {\n  return fc.hasPathCapability(p, CommonPathCapabilities.FS_SYMLINKS);\n}","tryCatchPattern":"catch (IOException e) { if (e.getMessage().equals(\"File system does not support symlinks\")) { /* fall back to pointer/manifest file */ } else throw e; }","preventionTips":["Probe fs.capability.paths.symlinks (or fc.supportsSymlinks()) once per filesystem and cache the result","Assume object stores have no symlinks; design pointer indirection as a data convention","Keep symlink-creating code paths behind a filesystem capability check so tests on any FS pass"],"tags":["symlink","unsupported-feature","object-store","filecontext","hadoop-fs"],"backgroundTag":"symlink-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}