Mods are the number one cause of basically everything
Before working through anything below: if you recently added, updated or removed a mod and something broke shortly after, start there rather than assuming it’s a hardware or hosting problem. Our mods guide covers dependencies and version matching, which together explain a large share of the crashes and connection failures reported here.
The five buckets
First, check the server is actually running: on a rented server, look at its status and console in the host’s panel rather than assuming a connect failure means something is broken. Also check that your game version matches the server’s exactly. If the server is up and you’re self-hosting, the most common cause is port forwarding: Vintage Story uses port 42420 by default — see the port forwarding steps in our playing with friends guide. If forwarding is set up correctly and it still fails, your connection may be on CGNAT, which blocks inbound connections entirely regardless of router configuration — a rented server sidesteps this since you’re not the one accepting the connection. If you would rather avoid port forwarding entirely, our best Vintage Story server hosting comparison covers the managed alternatives.
A short pause when the world autosaves (every 300 seconds by default) is normal. Beyond that, start with the basics from the official wiki’s performance advice: keep the save on an SSD and have at least 4 GB of system RAM free before starting the server. Also watch disk space, because the server shuts itself down when free space drops below DieBelowDiskSpaceMb (400 MB by default). After that, too many loaded chunks (MaxChunkRadius set too high) and entity overload from too many mobs or dropped items in one area are the two most common fixable causes, both covered with exact settings in our server settings guide.
A crash that started right after installing or updating a mod is a mod problem, not a server problem — the fix is usually reinstalling the correct version or checking for a missing dependency, both covered in the mods guide linked above. If the server won’t start at all after a game update, check the .NET runtime: Vintage Story runs on .NET, not Java, and the official wiki lists .NET 10 for version 1.22.0 and newer, .NET 8 for 1.21.x and .NET 7 for 1.18.8 to 1.20.x. Self-hosted Linux servers need the matching runtime installed; on a rented server, the host picks it (some panels have a .NET version setting).
Your safety net is the autosave interval plus backups: the server saves every 300 seconds by default (ServerAutoSave in servermagicnumbers.json), and stretching that interval means a crash loses more progress. See our settings guide for the details. Run /genbackup before risky changes; it makes a full copy of the save without pausing the server. The official wiki also recommends backing up before adding or removing mods and before updating the game, since removing a content mod from a save that used its blocks or items can leave them missing from the world.
Two mods touching the same recipe, block or system is the classic conflict pattern. Disable mods one at a time to isolate which one is responsible rather than guessing — our mods guide covers installing them a few at a time in the first place specifically to make this kind of isolation easier later.
How to actually find the cause
Guessing wastes time. These are the official tools for pinning down what’s actually happening.
Run this on the server (as the owner, or in single player). Any server tick that takes longer than the number of milliseconds you give (100 here) gets a breakdown written to server-main.txt. Let it run for a while during the lag, then check that file in the server’s Logs folder (inside its data path; %appdata%/VintagestoryData/Logs on a default Windows install) to see what’s actually consuming time. Run the same command again to stop logging.
The client-side equivalent, for diagnosing FPS drops rather than server lag. Use 20 if you’re usually above 60fps, or 40 if you’re usually above 30fps. Check client-main.txt in the client’s %appdata%/VintagestoryData/Logs folder afterward, and run the command again to turn logging off.
Turns on extended debug info. Type it before taking a screenshot of the frame profiler (Ctrl+F10) for extra diagnostic output — useful if you’re reporting a performance issue to a mod author or your host’s support team.
Symptom → likely cause
| Symptom | Likely cause | Fix |
|---|---|---|
| Can’t connect at all | Port not forwarded, or CGNAT | Check port forwarding; consider a rented server if on CGNAT |
| Brief pause every 5 minutes | Normal autosave (300 s default) | Nothing — this is expected behaviour |
| Server shuts itself down | Free disk space below 400 MB (DieBelowDiskSpaceMb) | Free up disk space; keep the save on an SSD |
| Won’t start after a game update | Wrong .NET runtime | .NET 10 for 1.22+, .NET 8 for 1.21.x |
| General tick lag with several players | MaxChunkRadius too high | Lower to 8–10 in serverconfig.json |
| Lag concentrated in one area | Entity overload (mobs/items) | Clear excess entities, lower entity tracking range |
| Crash right after a mod update | Version mismatch or missing dependency | Reinstall the correct mod version |
| Progress lost after a crash | Autosave interval stretched too far | Keep ServerAutoSave near 300 s; restore from backup if available |