Upgrading Vintage Story Dedicated Servers: Complete Maintenance & Migration Guide

Updating a Vintage Story server requires safely shutting down the host process, creating a full archive of the server data directory, and replacing core application binaries with the latest official release. Preserving the underlying database and JSON configurations ensures that world saves, player data, and custom parameters remain intact across minor and major release channels. Following an audited update routine eliminates database corruption, reduces administration downtime, and ensures immediate compatibility with new game engine builds.

Pre-Update Audits & System Backup Protocols

Executing a server software upgrade on a live Vintage Story instance demands a structured maintenance window. Before altering core binaries or applying patch updates, server administrators must audit environment dependencies, evaluate mod compatibility, and enforce system recovery snapshots. Minor releases within the same version branch (such as upgrading from version 1.19.3 to 1.19.8) generally preserve save compatibility natively, whereas major branch jumps (such as moving from version 1.18.x to 1.19.x) introduce database schema revisions and altered C# API hooks.

Maintenance Pre-Requisite Checklist

• Essential Administrative Tools: Secure Shell (SSH) terminal or Remote Desktop Protocol (RDP) client, elevated root or administrator privileges, file transfer protocols (SFTP/SCP), and an archive utility capable of gzip or zip compression.
• Target Directory Identification: Explicit knowledge of the server binary directory (containing VSServer.exe or VSServer executable) and the dedicated server data storage path (containing server.json, the saves folder, and custom server mods).
• Version Compatibility Verification: Access to official Vintage Story release notes to check for breaking API changes, database schema alterations, or required Microsoft .NET runtime updates (such as .NET 7 or .NET 8 dependencies depending on the target release build).
• Operational Benchmarks: Allocated maintenance window of 10 to 30 minutes, continuous database backup retention of at least three historical checkpoints, and a minimum of double the server directory's disk space available for temporary archive creation.

Executing the Vintage Story Dedicated Server Update Workflow

Follow this step-by-step procedure to perform a clean, lossless update on both Linux-based and Windows-based dedicated hosting environments.

Step 1: Notify Active Players and Initiate Graceful Shutdown

Never terminate a running Vintage Story server process abruptly via hard process kills or sudden terminal closures. Forced shutdowns interrupt ongoing SQLite database write operations to the world save file, which risks unrecoverable chunk corruption and inventory loss.

1. Connect to the game server as an operator or issue commands directly through the server console interface.
2. Broadcast an in-game warning to connected players detailing the impending maintenance reboot by running the server command /announce Server is shutting down for scheduled version update in 5 minutes.
3. Issue a follow-up warning at the one-minute mark to allow players sufficient time to log out safely in secure terrain.
4. Issue the graceful termination command /stop in the server console. This command triggers an explicit force-save of all modified world chunks, commits pending entity changes to the SQLite database, writes active player inventories to storage, and safely releases file locks.
5. Verify through your operating system process monitor (using ps aux | grep VSServer on Linux or Task Manager on Windows) that the server application has completely exited.

Warning: Terminating the host process while the server console displays active save operations will corrupt the main world database file located in the saves directory. Always wait for the terminal process to terminate completely before touching core directories.

Step 2: Create a Comprehensive Data Archive

Creating a isolated restore point before modifying any system binaries allows you to instantly roll back state if a mod incompatibility or database migration failure occurs during the update process.

1. Navigate to the parent folder containing your server data directory. By default, Vintage Story stores configuration files, active worlds, and player logs in a specific data folder. On Linux, this is typically located at ~/.config/VintagestoryData or a custom folder designated by the --datafolder execution flag. On Windows, this is found under %appdata%\VintagestoryData or within a local server directory.
2. Compress the entire data directory along with your existing server executable directory into a timestamped archive.
3. On Linux environments, execute a tarball compression command such as tar -czvf vs-backup-pre-update-$(date +%Y%m%d).tar.gz /path/to/vintagestorydata to construct a compressed snapshot.
4. On Windows host systems, create a ZIP archive of the server installation and application data directories using standard archiving software or PowerShell utility commands.
5. Move the generated archive to a secure secondary storage path outside of the active installation directory.

Pro-Tip: Always copy the entire data directory rather than just the world database file. Upgrades frequently modify internal server settings within server.json and save indexes within the data/saves subdirectory; preserving the entire structure ensures total state recovery.

Step 3: Fetch and Deploy New Application Binaries

Upgrading the application requires replacing existing program files with updated binaries downloaded directly from the official Vintage Story distribution servers.

1. Visit the official Vintage Story download portal and locate the tar.gz package for Linux or the zip/installer package for Windows matching your desired server version.
2. Download the package directly to your host machine. On head-less Linux hosts, use a network transfer utility command such as wget https://cdn.vintagestory.at/gamefiles/stable/vs_server_linux-x64_1.19.8.tar.gz replacing the version string with your target release.
3. Unpack the compressed archive into a temporary extraction directory.
4. Overwrite existing system executable files in your primary server installation directory with the freshly unpacked files. Ensure that you overwrite files like VSServer.dll, VSServer.exe, and core library files.
5. If running on a system systemd service framework on Linux, verify that binary execution permissions remain intact by setting executable permissions using chmod +x VSServer inside the application folder.

Warning: Do not unpack new server downloads directly into your dedicated data directory if you store application binaries and server data in the same combined folder without flags. Overwriting root directories without checking file targets can overwrite custom script files or localized mod configurations.

Step 4: Audit and Update Installed Server Mods

Modifications built for older Vintage Story API iterations frequently cause fatal startup exceptions when loaded by newer server binaries. Every major build update requires an audit of the Mods folder.

1. Navigate to the Mods directory located within your custom data folder path.
2. Cross-reference installed mod versions against the official Vintage Story Mod DB to locate updated releases designed for your target server version.
3. Remove outdated mod archive files (.zip or .dll) from the folder and insert the upgraded mod distributions.
4. Temporarily remove any client-side or server-side mods that have been abandoned or lack explicit compatibility updates for the target game build.
5. Keep a isolated staging folder of removed mods to systematically test re-introducing them once the core server platform successfully boots.

Step 5: Execute Startup and Monitor Migration Telemetry

With fresh binaries installed and mods updated, initiate the application start sequence while actively observing stdout console logs to track automated database migration processes.

1. Launch the server process using your standard operating system execution string, systemd service unit command (systemctl start vintagestory-server), or batch script. Ensure all custom startup parameters—such as --datafolder /path/to/data—are preserved.
2. Monitor terminal log outputs continuously during the initial boot phase. On major engine updates, Vintage Story will automatically run schema migrations against the SQLite world database. Do not interrupt this process, as converting large world databases can take several minutes.
3. Check the console output for successful load statements, including mod initialization confirmations, world load percentages, and final network port binding messages (e.g., Dedicated Server successfully bound to port 42420).
4. Connect to the upgraded server using an updated game client matching the target server build to verify world geometry integrity, player inventories, and land claim retention.

Dedicated Server Deployment Matrix

Selecting the proper deployment architecture determines how binaries are replaced, services are managed, and paths are preserved across update cycles. The table below outlines technical operational standards across different host environments.

Troubleshooting Common Upgrade Failures

Server Crash During Startup: System.NullReferenceException or Mod API Mismatch

• Root Cause: The server is attempting to load an outdated custom C# mod or library that calls deprecated or refactored API methods in the updated Vintage Story engine binaries.
• Actionable Fix: Open the latest log file located inside the logs/server-main.txt directory. Scroll to the bottom of the stack trace to identify the specific mod ID causing the exception. Move the identified mod package out of the Mods directory into a temporary storage folder, then restart the server. Repeat this process until all offending mods are identified and updated.

Database File Lock or SQLite Database Disk I/O Error

• Root Cause: A orphaned host process or background system service is still accessing the SQLite world save database file, preventing the newly updated binary from acquiring an exclusive write lock.
• Actionable Fix: Stop the server application. Identify ghost processes running in the background by executing pgrep -l VSServer on Linux or opening Resource Monitor on Windows. Force-terminate any remaining process instances using kill -9 [PID] or Task Manager. Confirm disk permissions on the saves directory allow full read/write access to the application user account before relaunching.

Configuration File Overwritten or Reset to Defaults

• Root Cause: Unpacking new binary archives directly over the installation root without setting a separate custom data folder path, causing the installer to overwrite the active server.json file with default parameters.
• Actionable Fix: Stop the server immediately. Extract your pre-update backup archive to a temporary directory, locate the backed-up server.json file, and copy it back into your active data directory. To prevent future occurrences, always launch the server process using the explicit CLI flag --datafolder /your/custom/data/path so binary installs never mingle with configuration data.

Frequently Asked Questions

Will updating my Vintage Story server delete my world save or player inventories?

No. Updating the server software replaces application code and engine files without deleting world files, provided your saves directory is stored securely within your designated data path. However, taking a manual backup before performing any version jump is critical to protect against potential database migration errors.

How do I update a Vintage Story server that runs inside a Docker container?

To update a containerized Vintage Story server, pull the latest container image tag from your image provider or rebuild your Dockerfile referencing the target version number. Ensure your persistent server storage (the data directory containing configurations and saves) is mapped to an external host volume so container deletion does not clear server progress.

What should I do if a new server version breaks world generation or custom mods?

If a major update breaks core gameplay elements or essential mods, restore your server to the previous state using your pre-update backup archive. Extract your backup files, replace the executable binaries with the previous stable version, restore the matching data folder snapshot, and wait for mod developers to publish compatible updates before re-attempting the upgrade.

How can I verify that my client and server versions match?

Run the command /serverinfo in the server console or view the terminal startup logs upon launch to confirm the running version string. Alternatively, clients attempting to connect with mismatched major or minor software builds will receive an explicit version mismatch error on the server selection screen detailing both local and remote build numbers.

Standardize Your Game Host Maintenance

Maintaining optimal server performance and data security requires standardized update protocols and continuous infrastructure monitoring. Upgrade your hosting hardware, automate backup routines, and establish high-performance Vintage Story game instances using modern enterprise hosting environments today.