A mod mismatch after an update is a reason to recover the previous working environment before trying another upgrade. Preserve the save before loading it without missing mods: saving a changed world can make restoration harder than copying its old mod ZIPs back.
The commands use the paths from our Factorio installation guide: /opt/factorio, /srv/factorio and service factorio. Substitute your actual paths if yours differ.
Freeze the state before repairing it#
Stop normally, check the shutdown log and archive the runtime directory:
sudo systemctl stop factorio
sudo journalctl -u factorio -n 80 --no-pager
sudo install -d -o root -g root -m 700 /var/backups/factorio
sudo tar -czf /var/backups/factorio/factorio-before-repair.tar.gz -C /srv factorio
sudo chmod 600 /var/backups/factorio/factorio-before-repair.tar.gz
Copy the archive securely outside the VPS. Keep the corresponding game installer too. If the log shows a failed save or forced shutdown, the archive may not include the last in-game progress. Do not post it publicly: settings can contain account tokens.
Find the first mismatch#
/opt/factorio/bin/x64/factorio --version
sudo journalctl -u factorio -b --no-pager
Compare the full game version with the client. Read from the start of this boot's journal so the first error is not hidden by failures that follow.
| First failure | Next action |
|---|---|
| Client/server game versions differ | Align the builds before changing mods |
| Mod fails during startup | Check its game branch, required dependency and enabled state |
| World loads; client reports mod mismatch | Compare the loaded mod versions and startup settings |
| Connection times out | Inspect networking and the server log; do not assume a mod problem |
Also check the logged config, write-data and mod paths. Files copied into a directory the service never reads cannot fix its loaded set.
Recover exact releases, then settings#
Inspect info.json in the failing mod. factorio_version declares its game branch; dependencies declares requirements and conflicts. Factorio's mod structure reference defines both. Editing the version field does not port the mod's code.
Keep the required ZIP releases, mod-list.json and mod-settings.dat together. Move unused archives to a backup directory rather than deleting them. mod-settings.dat is a binary settings file, not JSON. Startup settings require matching values and a restart; map and per-player settings have different scopes.
For recovery from a save, select it in the client's Load Game screen and Ctrl-click “Sync mods with save”. Normal save sync selects current releases; Ctrl-click selects the recorded versions. Joining a server syncs its exact loaded releases. Install mod ZIPs without unpacking them. These behaviours are described in the official mod guide.
Prepare the intended files in the client, close it, transfer the set to the server's active mod directory while the service is stopped, and preserve factorio:factorio ownership. Start the server and check which versions actually loaded before asking everyone to sync.
Headless --sync-mods can download missing mods only with service-username and service-token in player-data.json. Those are separate from server-listing credentials in server-settings.json; see the command reference.
Check Space Age separately#
The Linux headless package includes Space Age content, but that download grants no player entitlement. A Space Age game requires the expansion for every participant.
For a base-game group, use a compatible world with space-age, quality and elevated-rails disabled, and inspect third-party mods for DLC requirements. Do not disable expansion components on the only copy of a Space Age factory to find out whether it survives.
Roll back to the right world#
An older executable needs an older save. Wube explains that a newer save cannot be opened by an older game version in Friday Facts 353. Keep the pre-update save, binary, mods and settings as one recovery set.
Test an upgrade on a copy with a new filename. Migrations change world data; after loading, inspect critical production chains and trains, then connect a second player.
For rollback, choose the backup explicitly with --start-server /path/to/backup.zip instead of loading the latest save. Keep upgraded files elsewhere so the service cannot select them again. Very old factories may need intermediate game versions.
When organising supported instances in a panel for your own VPS, keep each factory's recovery set separately. A panel's instance controls do not establish mod or save compatibility.
