Fixed: Vintage Story Server Mod Sync Loop - Guide
One of the most common issues when joining a modded Vintage Story dedicated server is the infinite "Downloading Mods" loop. A player joins, the game downloads the mods, restarts, and then claims the mods are missing or mismatched, starting the cycle again. This guide provides the definitive 2026 solution for mod synchronization.
๐ The Mod Cache
Vintage Story stores server-side mods in a local cache. If a download is interrupted, the .zip file can become corrupted, leading to a permanent CRC mismatch.
๐ก๏ธ VINTOMATIC Integration
Most modern servers use the Vintomatic mod manager. If your server is not configured correctly, it will fail to serve mod files over the game's port.
How to Fix the Mod Sync Loop
1. Client-Side: Purge the Server Mod Cache
If you are stuck in a loop, the corrupted file is likely on your (the player's) machine. Navigate to your local Vintage Story data folder:
- Windows:
%appdata%/VintagestoryData/ServerMods/ - Linux:
~/.config/VintagestoryData/ServerMods/ - Fix: Delete all folders inside
ServerMods. This forces a clean redownload from the server upon your next join.
2. Server-Side: Verify the 'mod-list.json'
Server administrators must ensure that every mod in the /Mods/ folder is correctly listed in the mod-list.json with the enabled: true flag. If a mod is physically present but disabled in the config, the server will not send the data to the client, but the client will still expect it based on the world save metadata.
3. Increase Mod Download Timeout
For servers with large "Expansion" packs (like Primitive Survival or CarryOn), the default download timeout might be too short for players with slower connections. In your serverconfig.json, increase the networking timeout:
"ConnectionTimeout": 120,
"ModDownloadTimeout": 300Admin Pro-Tip: Never rename mod .zip files manually. Vintage Story uses the filename as part of the hash check. If you rename a file on the server, players will get an Invalid Checksum even if the code inside is identical.
Optimal Mod Hosting
Hosting many mods requires high-bandwidth networking. At Supercraft, we use a 10Gbps backbone to ensure that even 1GB modpacks are synchronized to players in seconds, eliminating the "Stuck at 99%" error.