Vintage Story Server Mods (1.22.7): Install, Control, Pin, Remove

Vintage Story Server Mods (1.22.7): Install, Control, Pin, Remove

Installing a mod on a Vintage Story server takes about thirty seconds. The question that decides whether your world survives the year is the opposite one: which mods is this server allowed to run, and who gets to change that? Dropping a zip in a folder is not a policy.

Vintage Story 1.22.7 answers that question server side, with a pair of lists hardly anyone uses because they are barely written down anywhere: a mod whitelist and a mod blacklist, both driven from /serverconfig. This page is the mechanism: where mods live, how to install one by file or from the in game mod database, how to hold a known good version instead of drifting to whatever was published last night, how to allow or block a modId, and how to get a bad mod off a live server.

Where mods live and how the server loads them

A dedicated server keeps its mods in a Mods folder inside the server's data directory. That folder decides what runs: the server reads it at startup and brings up whatever is sitting there. On a managed server it is the folder you see in the file manager or over FTP, so installing by file is a copy and nothing more.

Mods ship as .zip archives and they stay zipped: the server reads the mod out of the archive, and extracting it usually means the mod is not found. The filename normally carries the version, which is how you answer "which build is this server running" six weeks later.

The 1.22.7 server carries its mod startup path as a short run of strings, and they tell you what it is doing and in what order: Searching file system (including mods) for asset files, then Finished building index of asset files, then Reloaded lang file with mod assets, then Started mods. A mod that failed to open normally complains before the index is finished; anything that breaks after mods have started is runtime rather than loading. An internal blocked mod loading step sits alongside these, which is the clue that the blocked list is applied during startup rather than live, so restart after changing the lists if you want certainty. If a mod does not show up in game, read the server log around those lines first.

The two mod folders people mix up

Installing a mod by file

The file route always works, including when /moddb is switched off, and it is what you want for anything whose version you chose deliberately.

1. Back up first. Any mod change on a live world is a world change. Save management and backups.
2. Stop the server. Adding files underneath a running server gives you a half loaded state and a confusing log.
3. Copy the .zip into Mods, archive intact, version still in the filename.
4. Start the server and read the log through to the point where mods have started.
5. Confirm what loaded with /moddb list. Your expectations and that list should match exactly.

Add one mod at a time while building a set, so a failure has exactly one candidate cause. Install dependencies too, and treat a dependency as a mod like any other: it gets whitelisted, blacklisted and pinned on the same terms.

Installing with /moddb, from inside the game

The 1.22.7 server ships a /moddb command, described in its own help as a mod database utility for installing and removing mods. Its subcommands, with the help text each gives:

Run /help moddb on your own server before pasting anything. The text above is what 1.22.7 carries and it names the arguments, but the exact word order your build expects is something the command tells you in one line, and a guess does not.

search versus searchcompatible, and why the difference bites

Every release on the mod database declares which game versions it was built for. search shows only releases naming your exact current version; searchcompatible widens that to releases declaring compatibility with it. That is why a search can make a mod look abandoned: you update the server, run search, and half your set appears to have vanished because the authors have not cut a release naming the new point version. Nothing was abandoned. You asked a narrower question than you meant to.

searchfor and searchforc are the same pair aimed at a version you name, which makes them the planning tool: before moving a server to a new version, check whether your mod set has landed there yet. See updating a server without losing your world.

If the command answers with Command not available. Disabled probably by the host, /moddb has been switched off for this server. That is a host side decision, not a fault, and a restart will not change it. Install by file instead.

Pinning a version, so you do not inherit somebody else's bad night

This is the part that gets skipped and the part that costs worlds. A mod set that resolves to the latest of everything is a standing agreement to run whatever every author publishes, on their schedule, without review. When it is not fine, it arrives overnight and lands on every player at once.

1. Keep the archive you tested. That .zip is the artifact. Keep a copy off the server. Re-uploading it is the most reliable rollback there is, and it does not depend on the release still being published.
2. Name the game version on install. The install subcommand takes a forGameVersion argument after the modid, so you get a release built for the version you said rather than whatever the server is on when the command runs.
3. Use the version filtered searches when you move deliberately, with searchfor or searchforc.
4. Treat a version change as two steps: uninstall, then install the one you want. Two steps you chose beat one step that chose for you.
5. Write it down. A flat text file of modId, version, and the game version you last verified it against is the whole discipline, and the only thing that answers "what changed?" later. Long term modded server patterns goes further.

The backstop is the blacklist below. A pin holds only as long as everyone respects it; a blacklisted modId cannot load even if the file reappears.

The mod whitelist and the mod blacklist

Here is the mechanism most server owners do not know they have. The 1.22.7 server exposes two mod lists as subcommands of /serverconfig, the same family that holds the message of the day and the login flood protection: /serverconfig modwhitelist, help text Modify the mod whitelist, an allowlist of modIds, and /serverconfig modblacklist, help text Modify the mod blacklist, a denylist of modIds. Both take the same four operations, documented on each list:

One honest caveat, and read it before you type. The 1.22.7 help names the argument (modId) and spells out clear as a literal word, but it describes add, remove and show as actions rather than pinning down the word each expects. Run /help serverconfig modwhitelist and /help serverconfig modblacklist on your own server and read the line it gives back. That beats pasting a guess from any guide, this one included.

Which list do you want?

Most servers keep the blacklist empty and reach for it the day they need it. The whitelist earns its keep where a server has a curated identity or more than one person with file access, because it moves "what runs here" from a folder anyone can drop a file into to a list somebody has to edit on purpose.

They take modIds, not names

Both lists operate on modIds: the identifier declared inside the mod archive. Not the display name on the mod database, not the filename, and often neither of those spelled the way you expect, since a mod presented as "Carry Capacity" can have an id that is one lowercase word. Read the ids off the server with /moddb list, the same understanding of your mod set that the two lists use. Putting a display name on the whitelist and wondering why the mod is blocked fails silently.

Do not confuse this with the player whitelist

Vintage Story has two whitelists that share a word and nothing else. One controls which mods may load. The other controls which people may join.

The player command has its own add and remove for that whitelist too, and a separate /serverconfig WhitelistMode value reads and sets a whitelist mode on the player side. The mod lists are reachable only through modwhitelist and modblacklist, so if you mean mods, use those two and nothing else. The admin command reference covers players.

The rest of that family is the same kind of control at other layers: AntiAbuse, loginfloodprotection, temporaryipblocklist, motd, welcomemessage, MaxClients, and nopassword. File level settings are in the configuration guide, world level ones in the worldconfig reference.

On a modded server, your players run your mod set

Say this plainly, because it turns a mod choice into a security decision: on a modded Vintage Story server, connecting players receive and run the server's mods. That is the feature that makes modded servers usable at all, and it also makes your required mod list a software distribution channel pointed at everyone who joins.

The consequence follows directly. A mod whose harmful behaviour runs on the client does not need your server to be vulnerable to reach your players: the server is not the victim there, it is the delivery mechanism. A dependency mod is the sharpest version, because people run it without ever choosing it.

There is a worked example, with real version numbers and which releases are retracted, on the Config Lib page. The operational lesson: the two lists above are what you have when you need to say "not this one, not on my server", and the pinning habits are what stop you inheriting the next one automatically.

Getting a bad mod off a live server

Order matters, because the mod is on your players' machines as well as yours.

1. Tell players before you act. Somebody is mid download, and a mod set that changes under them produces exactly the symptoms reported as "your server is broken".
2. Back up. Removing a mod is a world change, not a file change.
3. Stop the server.
4. Remove the mod: delete the .zip from Mods, or use /moddb uninstall.
5. Add the modId to the blacklist with /serverconfig modblacklist. This is the step people skip and the one that makes removal stick: a deleted file can come back from a backup, a co-admin, or a dependency, but a blacklisted modId cannot load.
6. Restart, so the blocked list is applied at startup.
7. Verify both directions. The mod should be absent from /moddb list and present in the blacklist listing. Checking one tells you half the story.
8. Check what depended on it. Mods that required it will now fail to load and the log will say so. Find that out before announcing the all clear.
9. Tell players what to do on their side: they may need to clear the cached copy for your server before rejoining cleanly.

If the mod added blocks or items to your world, removing it removes those too. If that goes badly, recovering a modded world covers the restore path.

Hosted servers, and features that are gated

Better known in advance than discovered mid incident: the 1.22.7 server carries two messages you may run into.

• Can't access this feature, this server is in hosted mode. The build can refuse some /serverconfig operations when it is running in hosted mode.
• Command not available. Disabled probably by the host. The /moddb command can be switched off entirely by whoever runs the machine.

Neither means you have lost control of your mod set. It means the control moved. Installing and removing by file through a file manager or FTP depends on neither command. If you hit one of these, the useful question for your host is which applies and what they give you instead.

Quick reference

Release histories live on the official mod database at mods.vintagestory.at, where you can read which game versions a release was built for and whether it has been retracted.

Related pages

• Config Lib: which versions are safe, a dependency mod going wrong.
• Fixing the mod sync loop.
• Long term modded server patterns.
• Best Vintage Story mods in 2026.
• Admin commands, the configuration guide, the 1.22 update guide.
• Dedicated server installation.

Looking for managed Vintage Story server hosting? Supercraft runs Vintage Story dedicated servers with full file access to the Mods folder, daily backups, instant setup, and four regions, so a bad mod release is a restore rather than a lost world.