How To Update A Vintage Story Server: Complete Step-by-Step Administrator Guide

Upgrading a Vintage Story dedicated server requires safely shutting down the active instance, backing up world saves and configuration files, and replacing the core binaries with the latest release files. This procedure ensures your player progress, SQLite database structures, and server settings remain intact while transitioning to the latest version of the game. Following a systematic backup and migration protocol guarantees minimum downtime and zero data loss during major version transitions.

Pre-Update Checklist & Server Environment Requirements

Updating a Vintage Story dedicated server involves interacting directly with your host operating system's file directory and runtime environment. Because Vintage Story relies on a custom C# engine and modern .NET implementations, minor version mismatches between client machines and host servers will prevent players from connecting. Before executing an update, administrators must assess whether a release is a stable branch or a development candidate, evaluate API changes that might break existing server-side mods, and confirm that the host environment meets the performance demands of the updated engine.

To prevent directory corruption and ensure a swift recovery if a dependency conflict arises, assemble the required tools and verify your server access privileges beforehand.

• Administrative Access Credentials: Root or sudo-level SSH terminal access for Linux hosts, or Remote Desktop Protocol (RDP) administrator credentials for Windows virtual private servers.
• File Transfer Protocols: An active SFTP/FTP client, such as FileZilla or WinSCP, or a command-line utility like rsync for secure network file synchronization.
• Target Software Package: Access to the official Vintage Story Game Account Client Area to retrieve direct download URLs for the Linux headless tarball or the Windows Server archive.
• Underlying Dependencies: Verify that the .NET Runtime matching your target server version is installed on the host system. For Vintage Story version 1.18 and newer, the .NET 7.0 or .NET 8.0 Runtime is required, depending on the specific stable release build.
• Downtime Allocation: Plan for 10 to 20 minutes of total server offline time, allowing for sequential file transfers, database verification checks, and mod compatibility testing.

Step-by-Step Vintage Story Server Update Execution

Updating your server requires careful execution to prevent file corruption. Follow these steps to ensure a smooth transition to the newest game build.

Step 1: Notify Players and Execute a Safe Shutdown

Do not terminate your server process abruptly. Forcefully killing a Vintage Story server while players are actively chunk-loading or modifying block inventories can cause severe SQLite database corruption inside your world file.

First, broadcast a series of system warnings to active players using the in-game command line. Type the command /announce Server updating in 5 minutes. Please log off. in the server console or through an active SSH session running the server screen.

Once players have safely disconnected, execute the stop command by typing /stop into the server console. This action forces the server thread to commit all cached chunk modifications, write active player inventory data to the database, close open file streams, and terminate the hosting service cleanly. Verify that the process has completely stopped by checking your active task manager or running the command ps aux | grep Vintagestory on Linux environments.

Step 2: Create a Complete Server Backup

Never update server binaries without an offline backup of your data. The Vintage Story server separates its executable code from user data, which simplifies this step significantly.

Locate your server data folder. On a standard Windows installation, this path is typically found at C:\Users\YourUsername\AppData\Roaming\VintagestoryData. On Linux systems, it is often located at /var/vintagestory/data or within the home directory of your dedicated server user.

Create a compressed archive of this folder. For Linux administrators, execute a command such as tar -czvf vs-server-backup-before-update.tar.gz /var/vintagestory/data to bundle your saves, configuration files, and active mods into a single archive. Store this compressed backup in a secure directory separate from your active game server installation paths.

Step 3: Fetch and Extract the Latest Server Binaries

To update the server application files, you must retrieve the latest distribution package directly from the official Vintage Story distribution servers.

For Windows servers, log into your account on the game's official website, download the server ZIP package, and extract it directly over your existing installation directory. It is highly recommended to delete the old executable files first, specifically targeting directories containing library assemblies to prevent legacy .dll files from interfering with new engine calls.

For Linux headless servers, locate the download link for the specific game version tarball from the game's CDN. Open your server console and navigate to your temporary download directory. Download the archive using a web retrieval tool, for example, wget https://cdn.vintagestory.at/gamefiles/stable/vs_server_linux-x64_1.19.8.tar.gz (replace the version numbers in the URL with your target release).

Once downloaded, extract the archive directly into your server binary path, commonly located at /var/vintagestory/server, by executing the command tar -xzvf vs_server_linux-x64_1.19.8.tar.gz -C /var/vintagestory/server. If you are utilizing a systemd service file to manage the server background process, ensure that file ownership properties remain assigned to the dedicated game user by running chown -R vintagestory:vintagestory /var/vintagestory.

Step 4: Validate Mod Compatibility and Configuration Schemas

Major updates to Vintage Story often introduce API adjustments that can render existing mods incompatible, resulting in boot loops or server-side crashes.

Navigate to your data directory and access the Mods folder. Before initiating the server boot sequence, review your active mods against their updated versions published on the Vintage Story ModDB database. If a major engine version shift is occurring, temporarily relocate all third-party mods to a staging folder outside the active mod directory. This action permits you to test the stability of the base vanilla server first.

Next, open the serverconfig.json file using a text editor. Compare your existing parameters with any newly documented configuration keys introduced in the release notes of the target game version. If structural changes are detected, keep your existing configuration file intact but note any old parameters that may be deprecated.

Step 5: Launch the Server and Verify Initialization Logs

With the binaries replaced and the database backed up, you are ready to launch the updated server.

If your host operates via a Linux systemd service configuration, execute the command systemctl start vintagestory.service to initialize the daemon. If you are running the server manually or in a screen session on a virtual private server, execute the launch wrapper using the appropriate command, such as dotnet VintagestoryServer.dll --datapath /var/vintagestory/data.

Immediately tail the server initialization log file to catch early database errors or runtime exceptions. On Linux, monitor the startup logs using the command journalctl -u vintagestory.service -f, or inspect the server-main.txt log file inside your logs folder. Verify that the startup routine completes successfully and shows that the server is actively listening on your configured port, which defaults to UDP 42424.

Vintage Story Server Directory Paths & Architecture Reference

The physical location of executable files and active user data varies based on the target host operating system and deployment structure. The table below outlines standard absolute paths and execution parameters for primary hosting environments.

Vintage Story Server Update Errors & Diagnostic Resolutions

Updating system binaries can occasionally trigger environment mismatches or runtime failures. Below are common failure scenarios encountered during Vintage Story server upgrades, along with their root causes and resolutions.

Systemd Service Fails to Start Due to .NET Runtime Mismatch

• Root Cause: The upgraded version of Vintage Story requires a newer .NET framework version than the one installed on the host operating system. The server console exits immediately with a missing dependency error or an assembly load exception.
• Actionable Fix: Check your current .NET installation version by executing dotnet --info in your command terminal. If your system is running an older version, install the updated SDK or Hosting Bundle. For Ubuntu/Debian systems, execute sudo apt-get update && sudo apt-get install -y aspnetcore-runtime-8.0 (or the version specified in the Vintage Story release notes). After updating your system runtime, reload the systemd daemon configurations via sudo systemctl daemon-reload and restart your game server.

SQLite Database File is Locked or Corrupted on Boot

• Root Cause: An incomplete previous server shutdown or concurrent instances attempting to write to the same world database file has caused a database lock. This lock prevents the server from updating database schemas for the new game version.
• Actionable Fix: Search for and terminate any orphaned server processes still running in the background. Execute killall -9 dotnet or killall -9 mono on Linux to clear hung tasks. If the database remains locked, navigate to your saves folder, verify file permissions using ls -la, and confirm that the active user account running the server has write permissions for both the save directory and the specific world file. If write access is denied or restricted, reset permissions by executing chmod 755 -R /var/vintagestory/data.

Server Hangs or Crashes on Mod Loading Phase

• Root Cause: A mod compiled for a previous version of Vintage Story is attempting to call a class method or API endpoint that has been modified or removed in the updated server binaries.
• Actionable Fix: Shut down the server process. Navigate to your data directory's mod path and temporarily move all custom mod .zip files out of the folder. Re-launch the server to verify that the base vanilla game files boot cleanly. Once verified, return your mods to the folder one at a time, starting the server after each addition to identify the specific mod causing the crash. Check the mod developer's page for an updated build that supports your new game version.

Network Bind Failures on Restart (Port Already in Use)

• Root Cause: The operating system socket layer has not yet released UDP port 42424 after the server was shut down, or a zombie server process is still running on that port.
• Actionable Fix: Locate the process holding the port open by running the command ss -lupn | grep 42424 on Linux or netstat -ano | findstr 42424 on Windows. Once you identify the process ID (PID), terminate it manually using kill -9 PID (replacing "PID" with the actual number) on Linux, or by using the task manager on Windows. This frees up the port for your updated server instance.

Frequently Asked Questions

Can I update a modded Vintage Story server without losing my world?

Yes. You can update your server without losing your world as long as you back up your save directory before updating and make sure your server data folder remains completely separate from your server binaries. When you update, only the core game files are replaced, leaving your world databases intact. However, you must verify that all installed server-side mods are compatible with the new version of the game before allowing players to connect.

Where do I find the server download links for Vintage Story?

Direct server download files are located within the dedicated client area on the official Vintage Story website. You must log in using an account that owns a game license to view stable and unstable releases for Linux, Windows, and macOS. For automation scripts, you can copy the direct download address from the client page and download the files directly to your server using web retrieval tools.

How do I update a Vintage Story server running on Linux Ubuntu?

To update your server on Ubuntu, download the latest Linux headless tarball to your system. Stop the active server service, run a backup command to save your data, and extract the new tarball files directly over your existing server installation directory. Finally, adjust file permissions if necessary to match your dedicated game user, and restart your server system service.

What happens if I update my server but players haven't updated their game clients yet?

If a server is updated to a newer game version, players running older versions of the game client will be blocked from joining. When they attempt to connect, the game client will display an error message explaining that there is a version mismatch. To prevent connection issues, notify your community before updating and encourage players to match their client version with the server version using their game launcher.

Need Premium Performance for Your Vintage Story Community?

If you want to spend less time managing updates and diagnostics and more time building your world, transition your community to a dedicated hosting platform. Upgrade your hosting setup today to enjoy high-speed solid-state storage, automated backups, and instant game version switching.