How To Update A Vintage Story Server: Complete Admin Guide

Updating a Vintage Story dedicated server requires executing a graceful service shutdown, creating an isolated archive of the world database and configuration files, replacing outdated application binaries with the target release, and validating mod API compatibility. Following standard administrative procedures ensures database schema migrations process cleanly while preventing chunk corruption and connection mismatches between server instances and game clients. Most standard updates complete in under fifteen minutes on both Windows and Linux environments.

Pre-Update Server Preparation & Data Preservation Protocols

Upgrading a Vintage Story dedicated server involves modifying fundamental game binaries, underlying API references, and internal world database schemas. Skipping administrative safeguards before running update scripts risks unrecoverable corruption of SQLite save files, broken chunk generation, and severe mod instability. Server administrators must establish a controlled update workflow prior to modifying any environment files.

Before initiating any version transition, review the target release notes provided by the developers. Major version releases (such as transitioning from 1.18.x to 1.19.x) frequently alter C# API structures and engine mechanics, requiring concurrent updates to installed server-side mods. Minor point updates (such as 1.19.1 to 1.19.2) typically focus on bug fixes and performance stability, presenting minimal risk to active database schemas.

Pre-Flight Administrative Checklist

• Essential Management Access: SSH client (OpenSSH, PuTTY) or Remote Desktop Protocol (RDP) access, File Transfer Protocol (SFTP/FTP) credentials, and system administration privileges (sudo or Administrator).
• Target Binaries: Official target release archive (tar.gz for Linux distributions or .zip for Windows environments) downloaded directly from the official Vintage Story distribution servers.
• Prerequisite Runtimes: Verified installation of the required .NET Runtime framework corresponding to the target game version (Vintage Story 1.18+ requires .NET 7.0 or higher).
• Time & Resource Metrics: Estimated maintenance downtime of 10 to 20 minutes; local disk storage capacity equal to at least twice the current total size of the game installation directory for temporary backup archiving.

Step-by-Step Vintage Story Server Upgrade Procedures

Step 1: Terminate Active Server Processes & Notify Players

Never replace application files or alter system directories while the Vintage Story server daemon is active. Unsaved world data residing in system RAM will be lost, and open database handles on SQLite save files will lead to file corruption if binaries are overwritten mid-write.

1. Broadcast an in-game warning to active players using the server console or in-game chat interface by sending the command /announce Server going down for scheduled maintenance in 5 minutes.
2. Issue a manual save command to commit all cached entity data, chunk alterations, and player inventories to disk by typing /servermaster save in the server console interface.
3. Terminate the server process gracefully by sending the /stop command.
4. For managed system daemons on Linux environments, verify that the background process has fully released system locks by executing sudo systemctl stop vintagestory-server (or your designated service name). On Windows environments, ensure the command prompt window hosting VintagestoryServer.exe closes completely.

Warning: Avoid force-killing the server process using task termination commands like kill -9 or Task Manager termination unless the process is completely unresponsive. Forceful termination interrupts active database transactions, which can corrupt the main world database file.

Step 2: Execute a Complete Backup of Saves and Configurations

Creating a complete data snapshot is mandatory before extracting new server files. This permits instant rollbacks if a mod breaks compatibility or if the new engine version fails to boot on your host system.

1. Locate your server data directory. On default Windows installations, this is found under AppData/Roaming/VintagestoryData. On custom or Linux installations, this is typically located within your dedicated server root path or /var/vintagestory/data.
2. Identify the critical directories and files requiring preservation:
   
   
   • Saves: Contains all world database files (.db extension).
   • Mods: Contains installed server-side and universal mod packages (.zip files).
   • serverconfig.json: Holds game parameters, port bindings, administrator lists, and security flags.
   • worldconfig.json: Contains specific world generation rules and game mode settings.
3. Create a compressed archive of these files. On Linux command line, execute tar -czvf vs-server-backup-$(date +%F).tar.gz /path/to/vintagestory/data. On Windows, right-click the VintagestoryData folder and compress it to a standalone ZIP archive stored outside the main game directory.

Step 3: Download and Extract the Target Release Binaries

Vintage Story dedicated server releases are distributed as self-contained executable packages. Replacing files requires overwriting existing engine binaries while preserving local user data structures.

1. Download the correct server binary distribution corresponding to your host operating system directly from the official Vintage Story downloads portal. Ensure you select the Dedicated Server package rather than the game client archive.
2. Unpack the compressed archive to a temporary directory on your host machine.
3. Transfer the extracted application files into your existing Vintage Story server installation folder, deliberately overwriting old files when prompted. Core executable files including VintagestoryServer.exe, VintagestoryServer.dll, VintagestoryAPI.dll, and associated library directories must be fully replaced.

Pro-Tip: If you maintain your user data (Saves, Mods, serverconfig.json) in a separate custom data folder path passed via the --data path startup flag, you can safely wipe the entire old binary directory before extracting the new release files. This eliminates legacy, unused assemblies that could cause internal engine conflicts.

Step 4: Audit and Update Installed Mods

Server mods compiled for older versions of the Vintage Story C# API often crash updated server daemons during initialization. Mod updating must occur in lockstep with core binary updates.

1. Cross-reference your installed mods in the Mods directory against the official Vintage Story ModDB platform to check for updated versions matching your target server release.
2. Remove outdated mod archives (.zip) from the server Mods folder.
3. Place updated mod files directly into the Mods directory.
4. If an updated version of a critical mod is not yet available from its author, temporarily relocate that mod out of the active server directory to prevent application crashes during server startup.

Step 5: Launch the Server and Monitor Database Migration

With new binaries in place and mods audited, launch the application to trigger automatic internal schema migrations.

1. Start the server process. On Windows systems, run VintagestoryServer.exe or execute your batch launch script. On Linux systems, launch your start script or run sudo systemctl start vintagestory-server.
2. Open the primary server log file located at Logs/server-main.txt or stream live output using tail -f Logs/server-main.txt on Linux terminals.
3. Monitor the initialization sequence carefully. The game engine will automatically detect older SQLite save formats and run necessary migrations.
4. Verify that the console displays the final confirmation message indicating the server is running and listening on your configured port (default UDP/TCP 42420).
5. Attempt a client connection using an updated game client to confirm network stability, chunk rendering, and player permissions.

Platform Configuration Specs & Installation Binary Mapping

Different hosting environments require distinct binary targets and directory strategies during the update process. The table below outlines standard operational specifications across common operating systems and hosting platforms.

Server Failure Scenarios & Field Fixes

Scenario 1: Server Crashes on Startup with NullReferenceException or API Missing Method Error

• Root Cause: One or more installed mods inside the Mods directory were compiled for an older major C# API version and are calling methods or properties that were refactored or deleted in the target release.
• Actionable Fix: Stop the server. Move all files out of the Mods directory into a temporary staging folder. Relaunch the server. If the server boots successfully, move mods back into the active directory one by one or in small batches, restarting each time, until the precise breaking mod is identified in Logs/server-main.txt. Leave the breaking mod disabled until an update is published by the author.

Scenario 2: Players Receive Version Mismatch Error Upon Connection Attempt

• Root Cause: The server binary was successfully updated, but client machines are attempting to connect using an older or newer game build, OR the server executable was unpacked into the wrong directory, leaving old binaries active.
• Actionable Fix: Check the server console log upon boot to verify the exact string reported in the startup header (e.g., Running Vintage Story Server v1.19.3). If the server shows the old version, verify your execution pathing and batch script targets to ensure you are starting the updated executable file. If the server reports the correct version, instruct connecting players to match their game client build to the server version via the main game launcher.

Scenario 3: Database SQLite Locked or Corrupt File Error During Boot

• Root Cause: The previous server process was terminated forcefully (kill -9 or power loss), leaving temporary SQLite write-ahead logs (.db-wal or .db-shm) locked, or the user launched a second instance of VintagestoryServer.exe targeting the same database simultaneously.
• Actionable Fix: Verify no secondary server processes are running in the background using Task Manager (Windows) or ps aux | grep Vintagestory (Linux). Terminate lingering processes. If the database remains locked, navigate to the Save game folder and check for orphaned database lock files. Ensure full read/write permissions are granted to the user account executing the server daemon using chmod -R 755 /path/to/data.

Scenario 4: Linux Executable Fails to Run with Permission Denied Error

• Root Cause: Extracting the tar.gz binary archive under a non-privileged user account stripped the execute bit permissions from the binary files and shell scripts.
• Actionable Fix: Open a terminal, navigate to your server binary directory, and restore execution rights across all application binaries and scripts by executing chmod +x VintagestoryServer server.sh. Ensure the underlying system account owns the directory by running chown -R vintagestory:vintagestory /opt/vintagestory/.

Frequently Asked Questions

Will updating my Vintage Story server delete my existing world save?

No, updating game binaries does not automatically overwrite or delete your world saves, provided you do not manually erase your data directory. Core world database files reside in a separate path from main server engine files. However, creating a manual backup of your Saves directory prior to updating is mandatory to protect against unforeseen file corruption during engine database migrations.

Can I update a server directly across multiple major versions?

While minor updates can be installed sequentially without issue, skipping multiple major releases (for example, jumping directly from 1.16.x to 1.19.x) can fail due to cumulative database schema transformations and generation shifts. The safest strategy is to upgrade incrementally through each intervening major milestone version, launching the server once per major update to permit sequential database migrations.

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

Connect to your server via SSH, stop the running service using systemctl stop or your screen session console, navigate to your binary folder, and download the latest release tarball using wget. Extract the archive directly over your binary installation path using the tar command with the -xzf flags, restore executable permissions with chmod +x, and restart your systemd daemon or launch script.

What should I do if a server update breaks world chunk generation?

If new chunks fail to generate or display hard border seams after a major release, review your world configuration files and mod compatibility list. If the issue stems from engine-level terrain generation updates, you can use built-in administrator commands such as /land prune or restore your pre-update world database from your backup archive while waiting for a minor hotfix release from the developers.

How do I revert my Vintage Story server to a previous version if an update fails?

To roll back an update, terminate the current server process completely. Delete all files within the binary installation directory, download the previous working server release archive, and extract it to the binary path. Next, delete the current data directory and restore your pre-update backup folder (containing your original Saves, Mods, and serverconfig.json files) before relaunching the server executable.

Optimizing Server Performance Post-Update

Maintaining a stable multiplayer environment requires ongoing administrative oversight beyond file extraction. Ensure your server infrastructure runs smoothly by automating routine backups and monitoring live performance metrics.

If hosting complex worlds with heavy mod loads, consider utilizing managed dedicated hosting solutions optimized for high single-thread CPU performance and enterprise SSD storage to ensure continuous high-tps gameplay for your community.