Workshop upload from Linux preserves symlinks in depot, blocking all downloads for the app

[Trinedi]

Workshop upload from Linux preserves symlinks in depot, blocking all downloads for the app

Platform: Steam for Linux (native client)
Affected game: Europa Universalis V (AppID 3450310), but likely affects any game using ISteamUGC on Linux
Severity: High — one bad upload can block ALL workshop downloads for every Linux subscriber of that game

Summary

When a mod author on Linux uploads a Workshop item that contains a symlink (e.g. thumbnail.png -> /home/user/project/.metadata/thumbnail.png), Steam's upload process appears to preserve the symlink metadata in the depot manifest rather than resolving it to the target file's contents. When any user (including the uploader) subsequently subscribes and downloads, Steam's download pipeline attempts to recreate the symlink and fails with "Disk write failure." This failure cancels the entire download queue for that AppID, preventing all other subscribed Workshop items from downloading.

Steps to Reproduce

1. On Linux, create a mod directory where one file is a symlink to a file elsewhere on disk (e.g. thumbnail.png -> /home/user/project/thumbnail.png)
2. Upload the mod to Workshop via the game's built-in upload tool (ISteamUGC)
3. Subscribe to the mod

Expected Behavior

Steam should resolve symlinks during upload and store the actual file contents in the depot. On download, a regular file should be written.

Actual Behavior

Steam stores the symlink in the depot. On download, it attempts to create a symlink and fails:

[AppID 3450310] Update canceled: Failed updating depot 3450310 while creating symlink
(Disk write failure) ".../3664577264/.metadata/thumbnail.png"

This error repeats on every download retry and blocks all other Workshop downloads for the same AppID. In my case, a single broken mod (Workshop ID 3664577264) prevented 3 other unrelated mods from downloading. The error repeated dozens of times across multiple hours — see log excerpt below.

Impact

• Upload side: Any Linux mod author who uses symlinks in their mod directory (a common development workflow — symlink content from a git repo to the game's mod folder) will unknowingly upload broken mods.
• Download side: Any Linux user who subscribes to such a mod gets their entire Workshop download queue for that game stuck. There is no error shown in the Steam UI — mods silently fail to appear. The only evidence is in ~/.local/share/Steam/logs/workshop_log.txt.
• Queue blocking: Because Steam processes Workshop downloads sequentially per AppID, one failing item blocks all subsequent items. The user must manually unsubscribe from the offending mod AND delete stale files from steamapps/workshop/downloads/ to recover.

Workaround

For affected users:

1. Unsubscribe from the broken mod
2. Quit Steam
3. Delete ~/.local/share/Steam/steamapps/workshop/downloads/<appid>/
4. Delete ~/.local/share/Steam/steamapps/workshop/downloads/state_<appid>_*.patch
5. Restart Steam

For mod authors: Replace all symlinks with real file copies before uploading.

Suggested Fix

Two issues should be addressed:

1. Upload: Resolve symlinks to regular files during depot packaging (follow symlinks, store file contents)
2. Download queue: A single failing item should not block the entire download queue for an AppID. Skip the failing item and continue with the rest.

Log Excerpt (workshop_log.txt)

[2026-02-12 02:15:43] [AppID 3450310] Uploaded new content (ManifestID 8925622642185695715) for item 3664577264.
[2026-02-12 02:15:46] [AppID 3450310] Upload finished for workshop item 3664577264 : OK
[2026-02-12 22:53:24] [AppID 3450310] Subscribed to item 3664577264
[2026-02-12 22:53:26] [AppID 3450310] Update canceled: Failed updating depot 3450310 while creating symlink (Disk write failure) ".../3664577264/.metadata/thumbnail.png"
[2026-02-12 23:00:08] [AppID 3450310] Update canceled: Failed updating depot 3450310 while creating symlink (Disk write failure) ".../3664577264/.metadata/thumbnail.png"
[2026-02-12 23:00:09] [AppID 3450310] Update canceled: Failed updating depot 3450310 while creating symlink (Disk write failure) ".../3664577264/.metadata/thumbnail.png"
[2026-02-12 23:33:35] [AppID 3450310] Update canceled: Failed updating depot 3450310 while creating symlink (Disk write failure) ".../3664577264/.metadata/thumbnail.png"
[2026-02-13 00:03:04] [AppID 3450310] Update canceled: Failed updating depot 3450310 while creating symlink (Disk write failure) ".../3664577264/.metadata/thumbnail.png"

The same error repeats 30+ times across 2 hours. Other subscribed items (3665081158, 3665118031) never download.

Related

• ValveSoftware/steam-for-linux#3997 — related symlink handling issue in Workshop uploads on Linux