How to Update Mods on your Vintage Story Server

Update mods on your Vintage Story server by replacing the old mod file with a newer version. Because most mods change their .zip filename between releases, the old file won’t be overwritten automatically - you’ll need to remove it first.

There are two ways to do this: uploading the new file manually over SFTP, or letting the server fetch it with the /moddb install command. Both approaches take about the same amount of effort; pick whichever fits your workflow.

Method 1: Manual Upload via SFTP

Use this method if you prefer to manage files directly or if you’re updating several mods at once.

1. Head to mods.vintagestory.at, find the mod you want to update, and download the latest .zip release to your computer.
2. In the Game Control Panel, stop the server and wait for it to fully shut down before continuing.
3. Connect to your server via SFTP and navigate to the data/Mods folder.
4. Delete the existing .zip file for that mod.
5. Upload the new .zip you downloaded in step 1.
6. Start your server.

Method 2: /moddb install Command

Use this method if you’d rather not handle files directly. The server will download the latest version from the Vintage Story Mod Database for you.

Before running the command, you’ll need the mod’s ID. You can find it on the mod’s page at mods.vintagestory.at - it’s the short identifier in the URL, not the display name. Mod IDs are more reliable than names since names can contain spaces or special characters.

1. Stop your server and wait for it to fully shut down.
2. In the Game Control Panel, open the file manager and navigate to data/Mods.
3. Delete the existing .zip file for the mod you’re updating.
4. Start your server, then run the following command from the server console in your control panel or from in-game if you have operator access:

   /moddb install [modid]

Replace [modid] with the mod’s actual ID from the Mod Database. 5. Once the download completes, restart your server for the new version to load.

Troubleshooting: Mod Update Broke Your World

If your server fails to load chunks or crashes after updating a mod, the new version may be incompatible with data your world has already saved. Common signs include errors mentioning mainThreadLoadChunkColumn or ChunkColumnLoadRequest, or messages about failing to deserialize a block entity from a specific mod.

Identify the Offending Mod

This is the fastest way to confirm whether a specific mod is the cause. Renaming, rather than deleting, lets you restore the file if it isn’t.

1. Stop your server and wait for it to fully shut down.
2. In the Game Control Panel sidebar, click File Manager.
3. Navigate to data/Mods/.
4. Rename the suspect .zip (for example, examplemod_1.0.0.zip to examplemod_1.0.0.zip.disabled).
5. Start your server.
6. Watch the console output. If the chunk-loading errors stop, you’ve found the cause.

If the errors continue, rename the file back and repeat with the next suspect mod.

Recover Your World

Disabling the mod stops new errors but does not repair chunks that have already been written with the broken mod’s data. The most reliable recovery is to restore a backup taken before the update. See Restoring a Backup.

If no pre-update backup exists, an older version of the same mod may still be able to read the world. Open the Files tab on the mod’s ModDB page and try the version that was active when your world was last stable. This is not guaranteed. Once a newer mod has written its own data, an older build may not always read it back.

Avoid This Next Time

• Take a manual backup before updating any mod or your Vintage Story server version. See Restoring a Backup.
• Test mod updates against a copy of your world, not the live one.
• Vintage Story game version changes can also break old saves. If you suspect the game version is at fault, see Changing Vintage Story Server Version.

Still Not Working?

If you can’t identify the bad mod or your world is unrecoverable, contact our support team with:

• Your Server UUID
• The exact error lines from the server console (especially any at Vintagestory... stack traces)
• Which mod you were updating, including the old and new versions