Fixed: Vintage Story Server Mod Sync Loop (Guide)

Fixed: The Vintage Story Server Mod Sync Loop

Checked on 14 October 2026 against the Vintage Story 1.22.7 client and server.

When you join a modded server, the game compares the server's mods with yours. If you are missing some, it asks You are missing N mods to join this server, shall I attempt to download them from the mod database?, downloads them from the official Mod DB, says All mods downloaded, ready to join this server! and connects. A "sync loop" is what you see when that last step never succeeds. This guide explains what the game actually does, so you can find which step is failing.

How the Game Fetches a Server's Mods

• The source is the Mod DB, not the server. The server only tells your game which mods and versions it runs; your game downloads them from the official Mod DB. A mod or a version that is not on the Mod DB cannot be fetched this way.
• Each server gets its own folder. Downloads go to ModsByServer in your data folder, in a subfolder named after the server's address and port: %APPDATA%\VintagestoryData\ModsByServer\ on Windows, ~/.config/VintagestoryData/ModsByServer/ on Linux, ~/Library/Application Support/VintagestoryData/ModsByServer/ on macOS. The game only loads that folder when you join that server.
• Your own copy of a mod is set aside if its version differs. When your Mods folder holds a different version of a mod the server runs, the game leaves yours out for that server and needs the server's version instead.
• Mods are matched by mod ID and network version, not by file name, so renaming a .zip does not break anything.
• Your own mods' dependencies come from the same place. When a mod you added is missing a dependency, the game offers to download it (Missing mod dependencies), and you may see that screen several times until everything is resolved.

How to Fix the Mod Sync Loop

1. Player side: read the message, then clear that server's folder

• Unable to download some mods from the mod database. You'll have to manually install N mods. Sorry! The server runs a mod or a version the Mod DB does not have (a private build, a removed release, or a mod from elsewhere). Ask the admin for the exact files and put them in your Mods folder.
• Sorry, cannot connect, you need the following mods installed followed by a list: the download did not happen or did not finish. Delete the server's subfolder in ModsByServer and join again for a clean download.
• Sorry, cannot connect, you are missing following mods: ..., furthermore I was unable to load the mods ..., followed by a request to check the log files. A mod downloaded but failed to load on your side. The reason is in client-main.log in your data folder's Logs; usually it is a mod that needs a different game version.
• A mod requires v... of the game: update your game to at least that version.
• Incompatible Server Version is not a mod problem: your game and the server use different network versions. See unable to connect to server.

2. Server side: keep the mod list downloadable

• Run Mod DB releases. Players can only auto-download versions that exist on the Mod DB. If you run a private or patched build, hand the files to your players yourself.
• Check the server log after every mod change. server-main.log shows which mods loaded and which failed; a mod that fails on the server will not sync correctly either.
• Mind the mod lists. The server sends its /serverconfig modblacklist and modwhitelist to every client, and the client then refuses blacklisted mods, or with a whitelist, any client-side mod not on it. See installing mods.
• Client-only mods do not belong on the server. Mods marked client side on the Mod DB are each player's choice; mods marked server side, such as Terra Prety, are never sent to players.

1.22-specific mod sync issues

1.22 moved the game to .NET 10 and changed parts of the modding API, so many mods that ship compiled code needed a new release, and a 1.21 build of such a mod may fail to load on 1.22. After a game update, update the server's mods to releases listed for the new version, then have players delete the server's ModsByServer subfolder before their first join, so they fetch the new versions rather than reuse old downloads. Our modpack doctor checks a whole Mods folder against the Mod DB listings for the version you want to run.

Per-mod manifest discipline for long-term servers

If you run a long-term server (months/years), keep a text file tracking each mod's version and last-verified-compatible game version. When the game updates, walk down the list and verify each entry before changing anything. This prevents the cascade where one mod's update breaks the entire sync chain. See our long-term modded server guide for the full discipline.

Optimal Mod Hosting

Because players fetch mods from the Mod DB, your server's bandwidth is not what makes a big modpack slow to join. What helps is a mod list built from Mod DB releases. On Supercraft, the server panel's mod browser installs mods straight from the Mod DB, so the versions your players are asked to download are the ones the Mod DB can deliver.