Skip to content

Repair MO2

Jump to bottom
Bobby Comet edited this page Sep 12, 2026 · 1 revision

Kalium can repair Mod Organizer 2 application files on an existing managed instance without creating a new Steam game, AppID, or Wine prefix.

Instance data (mods, profiles, downloads, etc.) is handled only if you choose to back it up and restore it. Those steps are optional and never run silently.

Concepts

Two kinds of state

Application state (what Repair replaces)

  • ModOrganizer.exe and related binaries
  • Stock MO2 plugins / runtime files
  • USVFS DLLs (Kalium re-applies 0.5.7.2 after repair when possible)
  • Other files that ship with a fresh MO2 archive

Instance state (optional Backup / Restore)

Path Typical contents
mods/ Installed mods (can be very large)
downloads/ Nexus / manual archives
profiles/ Load orders, profile ini, separators
stylesheets/ UI themes
overwrite/ VFS writes — may include SKSE output, shaders, generated files
ModOrganizer.ini Game binding, custom executables, settings

What is never touched

  • Steam non-Steam shortcut / AppID
  • Proton selection in config.vdf
  • Wine prefix: …/steamapps/compatdata/<appid>/pfx

Repair always uses the same install folder and therefore the same prefix.

Safety workflow

Backup → Confirm → Repair → Test → Restore
Step Who starts it Purpose
Backup You Copy instance data outside the MO2 folder; Kalium verifies the copy
Confirm You Explicit checkbox / decision that the backup looks complete
Repair You Replace application files only (no automatic restore)
Test You Launch MO2 from Steam; confirm the original problem is gone
Restore You Copy instance data back from the backup folder

Do not restore until you have tested the repaired application. That way a bad restore cannot hide a failed repair.

Backup location rules

  • Backups must not live inside the MO2 install directory (Kalium refuses nested paths).

  • Default suggestion (same drive, sibling folder):

    MO2:     /mnt/sda1/Games/MO2
Backup:  /mnt/sda1/Games/MO2_backups/MO2_YYYYMMDD_HHMMSS/

  • You may browse to any other directory (another folder on the same disk, external drive, etc.).

GUI usage

  1. Open Settings.
  2. Select the managed MO2 instance in the prefix list.
  3. Click Repair MO2.

Dialog stages

  1. Select instance folders to include in backup/restore (downloads and overwrite are optional and off by default).
  2. Choose backup location (pre-filled with the sibling MO2_backups/… suggestion).
  3. Backup instance data — wait until status reports verification success.
  4. Tick “I have verified the backup folder looks complete”.
    • Until this is checked, Repair stays disabled (unless you skip backup).
  5. Optionally enable remove backed-up folders after repair so you can test a clean MO2 (data remains only in the backup until Restore).
  6. Repair application files.
  7. Test — launch from Steam, verify, fully exit Steam and MO2.
  8. Restore instance data from backup when ready (or skip and copy manually).

Skip automated backup

Use “Skip backup — repair application only” if you already have a manual copy or only need fresh MO2 binaries. Instance folders left on disk are not deleted by a normal repair unless you opted into “remove backed-up folders.”

Manual checklist

The dialog includes Show manual backup checklist (same text as kalium fix-mo2 … checklist).

Caveats

  • Some mods do not survive a filesystem copy (locks, junctions, extreme path lengths, antivirus). Those may need a re-download from Nexus.
  • Large lists take time — overhaul-heavy setups on HDD can take an hour or longer to back up or restore. SSDs are faster but not free.
  • overwrite/ is not “just mods”; restoring it can bring back stale generated data. Prefer leaving it unchecked unless you need it.
  • After repair, Kalium attempts to re-apply USVFS 0.5.7.2, theme, VFS max_memory, and custom-executable path fixes.

CLI reference

kalium fix-mo2 -p <MO2_PATH> <action> [options]

MO2_PATH is the folder that contains (or should contain) ModOrganizer.exe — the same managed install you use with Steam.

Actions

Action Description
checklist Print the manual backup checklist and exit
backup Copy selected instance data to a backup folder and verify
repair Replace MO2 application files only (no restore)
restore Copy instance data from --backup-dir into the MO2 path

Common options

Option Applies to Description
-p / --path all MO2 install path (required)
--backup-dir backup, restore Output dir for backup; input dir for restore. If omitted on backup, uses <parent>/MO2_backups/<name>_<timestamp>
--no-mods backup/restore selection Exclude mods/
--with-downloads selection Include downloads/ (excluded unless set)
--no-profiles selection Exclude profiles/
--no-stylesheets selection Exclude stylesheets/
--with-overwrite selection Include overwrite/ (excluded unless set)
--fresh-ini selection Exclude ModOrganizer.ini
--remove-instance-after-backup repair After a confirmed backup strategy, delete selected instance folders from the install so you can test a clean MO2

Examples

Print the manual checklist:

kalium fix-mo2 -p ~/Games/MO2 checklist

Backup with defaults (mods, profiles, stylesheets, ini → sibling MO2_backups/…):

kalium fix-mo2 -p /mnt/sda1/Games/MO2 backup

Backup to a chosen folder, including downloads:

kalium fix-mo2 -p /mnt/sda1/Games/MO2 backup \
  --backup-dir /mnt/sda1/Games/MO2_backups/manual_2026 \
  --with-downloads

Repair application files only (after you have confirmed a backup, or if you skip backup):

kalium fix-mo2 -p /mnt/sda1/Games/MO2 repair

Repair and remove backed-up instance folders from the install (clean test):

kalium fix-mo2 -p /mnt/sda1/Games/MO2 repair --remove-instance-after-backup

Restore after a successful test launch:

kalium fix-mo2 -p /mnt/sda1/Games/MO2 restore \
  --backup-dir /mnt/sda1/Games/MO2_backups/MO2_20260912_150051

Restore only profiles + ini from that backup:

kalium fix-mo2 -p /mnt/sda1/Games/MO2 restore \
  --backup-dir /mnt/sda1/Games/MO2_backups/MO2_20260912_150051 \
  --no-mods --no-stylesheets

Recommended CLI sequence

# 1) Backup
kalium fix-mo2 -p /path/to/MO2 backup
# 2) Inspect the printed backup path in a file manager
# 3) Repair application
kalium fix-mo2 -p /path/to/MO2 repair
# 4) Launch MO2 from Steam, verify, fully exit Steam + MO2
# 5) Restore when ready
kalium fix-mo2 -p /path/to/MO2 restore --backup-dir /path/to/backup

Levels of control

  1. Automated backup + confirm + repair + optional restore (GUI or CLI)
  2. Your own backup folder + Kalium restore (restore --backup-dir …)
  3. No Kalium backup — repair only, then copy folders by hand after a test launch

In all cases the Proton prefix under compatdata remains the same instance Kalium already registered. '''

Clone this wiki locally