seaweedfs/seaweedfs · error · UnsupportedOperationException

Filesystem does not support symlinks!

Error message

Filesystem does not support symlinks!

What it means

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.

Source

Thrown at other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedFileSystem.java:373

     *         write operations such as <code>append</code>, or
     *         <code>false</code> if a background process of adjusting the length of
     *         the last block has been started, and clients should wait for it to
     *         complete before proceeding with further file updates.
     * @throws IOException                   IO failure
     * @throws UnsupportedOperationException if the operation is unsupported
     *                                       (default).
     */
    @Override
    public boolean truncate(Path f, long newLength) throws IOException {
        throw new UnsupportedOperationException("Not implemented by the " +
                getClass().getSimpleName() + " FileSystem implementation");
    }

    @Override
    public void createSymlink(final Path target, final Path link,
            final boolean createParent) throws IOException {
        // Supporting filesystems should override this method
        throw new UnsupportedOperationException(
                "Filesystem does not support symlinks!");
    }

    public boolean supportsSymlinks() {
        return false;
    }

    /**
     * Create a snapshot.
     *
     * @param path         The directory where snapshots will be taken.
     * @param snapshotName The name of the snapshot
     * @return the snapshot path.
     * @throws IOException                   IO failure
     * @throws UnsupportedOperationException if the operation is unsupported
     */
    @Override
    public Path createSnapshot(Path path, String snapshotName)

View on GitHub (pinned to 1c926e8fac)

Solutions

1. Guard with supportsSymlinks() before attempting, and branch to an alternative (copy, or write a small manifest file holding the target path).
2. Restructure to avoid symlinks: use rename-based promotion of versioned directories instead of a link indirection.
3. If symlinks are essential, front the data with an HDFS/local layer that supports them and store bulk data on SeaweedFS.

Example fix

// before
fc.createSymlink(target, link, false); // UnsupportedOperationException

// after — capability check + manifest fallback
if (fs.supportsSymlinks()) {
    fc.createSymlink(target, link, false);
} else {
    try (FSDataOutputStream out = fs.create(link, true)) {
        out.writeUTF(target.toString()); // pointer file read by consumers
    }
}

if (fs.supportsSymlinks()) { // SeaweedFileSystem returns false (SeaweedFileSystem:377)
    fc.createSymlink(target, link, createParent);
} else {
    // write a pointer/manifest file instead of a symlink
}

boolean canSymlink = fs.supportsSymlinks(); // documented capability probe

try {
    fc.createSymlink(target, link, false);
} catch (UnsupportedOperationException e) {
    LOG.warn("Symlinks unsupported on {}", fs.getUri().getScheme());
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Not implemented by the {getSimpleName} FileSystem implementa
• Failed to create file: {path}
• Not a directory: {parent}
• Failed to append to file: {path}
• Path is a file: {path}

AI-assisted analysis of seaweedfs/seaweedfs@1c926e8fac (2026-08-15). Data as JSON: /api/errors/de72262fa527ffe9. Report an issue: GitHub.