{"record":{"id":"de72262fa527ffe9","repo":"seaweedfs/seaweedfs","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":"other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedFileSystem.java","lineNumber":373,"sourceCode":"     *         write operations such as <code>append</code>, or\n     *         <code>false</code> if a background process of adjusting the length of\n     *         the last block has been started, and clients should wait for it to\n     *         complete before proceeding with further file updates.\n     * @throws IOException                   IO failure\n     * @throws UnsupportedOperationException if the operation is unsupported\n     *                                       (default).\n     */\n    @Override\n    public boolean truncate(Path f, long newLength) throws IOException {\n        throw new UnsupportedOperationException(\"Not implemented by the \" +\n                getClass().getSimpleName() + \" FileSystem implementation\");\n    }\n\n    @Override\n    public void createSymlink(final Path target, final Path link,\n            final boolean createParent) throws IOException {\n        // Supporting filesystems should override this method\n        throw new UnsupportedOperationException(\n                \"Filesystem does not support symlinks!\");\n    }\n\n    public boolean supportsSymlinks() {\n        return false;\n    }\n\n    /**\n     * Create a snapshot.\n     *\n     * @param path         The directory where snapshots will be taken.\n     * @param snapshotName The name of the snapshot\n     * @return the snapshot path.\n     * @throws IOException                   IO failure\n     * @throws UnsupportedOperationException if the operation is unsupported\n     */\n    @Override\n    public Path createSnapshot(Path path, String snapshotName)","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/seaweedfs/seaweedfs/blob/1c926e8fac8e8001ce25efa1027c90b02b4a1804/other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedFileSystem.java#L355-L391","documentation":"UnsupportedOperationException('Filesystem does not support symlinks!') thrown unconditionally by SeaweedFileSystem.createSymlink() (seaweed.hdfs.SeaweedFileSystem:373). Symlinks are not supported, and the class also reports this via supportsSymlinks() == false (seaweed.hdfs.SeaweedFileSystem:377), which is the documented way to detect the limitation BEFORE attempting creation.","triggerScenarios":"Calling FileContext.createSymlink(target, link, createParent) or otherwise reaching FileSystem.createSymlink on a seaweedfs:// path; symlink-aware tools (e.g. some archivers, distcp with -p symlink handling, FileContext-based scripts) creating links.","commonSituations":"Porting shell-style workflows ('ln -s') to Hadoop FileSystem APIs; deployment layouts that point a fixed path at versioned directories via symlinks; FileContext code paths that assume symlink support on any filesystem.","solutions":["Guard with supportsSymlinks() before attempting, and branch to an alternative (copy, or write a small manifest file holding the target path).","Restructure to avoid symlinks: use rename-based promotion of versioned directories instead of a link indirection.","If symlinks are essential, front the data with an HDFS/local layer that supports them and store bulk data on SeaweedFS."],"exampleFix":"// before\nfc.createSymlink(target, link, false); // UnsupportedOperationException\n\n// after — capability check + manifest fallback\nif (fs.supportsSymlinks()) {\n    fc.createSymlink(target, link, false);\n} else {\n    try (FSDataOutputStream out = fs.create(link, true)) {\n        out.writeUTF(target.toString()); // pointer file read by consumers\n    }\n}","handlingStrategy":"validation","validationCode":"if (fs.supportsSymlinks()) { // SeaweedFileSystem returns false (SeaweedFileSystem:377)\n    fc.createSymlink(target, link, createParent);\n} else {\n    // write a pointer/manifest file instead of a symlink\n}","typeGuard":"boolean canSymlink = fs.supportsSymlinks(); // documented capability probe","tryCatchPattern":"try {\n    fc.createSymlink(target, link, false);\n} catch (UnsupportedOperationException e) {\n    LOG.warn(\"Symlinks unsupported on {}\", fs.getUri().getScheme());\n}","preventionTips":["Always consult FileSystem.supportsSymlinks() before symlink creation — it exists precisely for this.","Avoid symlink-based version switching in pipelines; use rename-based promotion which works everywhere.","Remember the UOE is unchecked and will not be caught by catch(IOException)."],"tags":["java","hadoop","seaweedfs","unsupported-operation","symlink","filesystem"],"backgroundTag":null,"analyzedSha":"1c926e8fac8e8001ce25efa1027c90b02b4a1804","analyzedAt":"2026-08-15T15:37:02.018Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}