Minecraft Server Updater

This mod is experimental!

Minecraft Server Updater (MSU) is a server-side Fabric utility for keeping a Minecraft server up to date with Modrinth-backed checks, safe staging, wrapper-based installs, automation, and rollback support.

MSU is designed for server owners who want update control without replacing live jars while the server is running.

Core idea:
Check what is outdated, stage safe updates into a holding area, then let the wrapper apply them cleanly before the next server boot.

---

Highlights

• Safe update flow: check → stage → apply on restart
• Modrinth-backed mod resolution
• Supports mod lists, reference mod folders, and .mrpack files
• Fabric Loader / server launcher maintenance
• Optional Minecraft version upgrade checks
• Self-update support for MSU
• Automation modes for check, stage, or install workflows
• Rollback and boot verification
• Operator-only /msu commands
• Readable status output with clear safe-to-stage reasons

---

✨ Feature set

Safe check → stage → apply workflow

MSU does not replace running mod jars while the Minecraft server is live.

Instead, it uses a three-step process:

1. Check — query Modrinth and inspect the configured source.
2. Stage — download or prepare replacement files into .minecraft-server-updater/.
3. Apply — on the next wrapper start, staged files are installed before Fabric starts.

This keeps update actions predictable and avoids modifying jars that the server is currently using.

Mod update checks

MSU checks whether configured mods have newer compatible builds for the Minecraft version the server is running right now.

Supported mod sources:

Source type	What it does
mod-list	Tracks one Modrinth project slug, id, or exact name per line in .minecraft-server-updater/mod-list.
mods-folder	Uses jars in a reference folder as the managed mod set.
mrpack	Uses a Modrinth pack file or URL as the managed source.

Mod-list entries resolve only by direct Modrinth project id/slug or an exact search hit — MSU does not guess from ambiguous names.

Server maintenance

MSU can check and stage server-side maintenance for the current Minecraft version, including Fabric Loader and launcher sync when enabled.

Minecraft upgrades

When server-upgrade is enabled, MSU can check readiness for:

• Latest Minecraft release
• A specific target Minecraft version

Server upgrades are separate from routine mod checks. Mod checks always target the version the server is actually running. Server upgrade checks target the configured upgrade version and may include:

• Minecraft server jar
• Fabric launcher / loader for the target version
• Fabric API for the target version (shown under server update candidates, not as a normal mod-list update)
• Optional mod preflight for the upgrade target when enabled

Self-update

MSU can check whether a newer MSU build is available on Modrinth and stage its own replacement for the next restart. Server upgrades to a new Minecraft version may require a target-compatible MSU build to be staged together.

Combined staging

/msu stage all can combine safe selected targets into one staged restart plan, allowing server maintenance, mod updates, self updates, and compatible Minecraft upgrades to apply on one restart with one backup.

If a server upgrade is configured but not safe to stage, combined staging stops there and does not stage other targets until server preflight is resolved.

---

📋 Understanding check output

MSU reports safety on separate lines so you can see whether staging is allowed and why not.

Safe-to-stage lines

Line	Meaning
Server safe to stage: true	Server maintenance or upgrade can be staged.
Server safe to stage: false; …	Server staging is blocked; the reason is on the same line (for example missing MSU or Fabric API on Modrinth for the target version, or mod preflight failure).
Safe to stage mods: true/false	Whether /msu stage mods is allowed for the running Minecraft version.
Mods stage blocked: …	Shown when mod staging is blocked (for example no updates available, unknown jars, policy blocks, or mrpack exact-pack issues).
Mods ready for target: true/false	Whether managed mods look ready for a configured server upgrade target (preflight only; not the same as “updates available today”).

Two Minecraft versions in one check all

/msu check all can show both:

• check server — uses the upgrade target (for example 26.2) when upgrade is enabled
• check mods — uses the running version (for example 26.1.2)

That is intentional, but easy to misread. Example:

• Server section: Fabric API [missing → 0.152.1+26.2] means the server upgrade will install Fabric API for the target version — not that your mod checker found a routine mod update.
• Mod section: 0 updates available means nothing needs staging on the version you are running now, even if an upgrade is planned.

What blocks stage all

Combined staging follows safety in order:

1. If a server upgrade is available but Server safe to stage: false, stage all stops and does not stage mods or self until server preflight passes.
2. Mods are included when safe for the combined plan — including some upgrade cases where mods have no updates on the running version but are still ready for the target.
3. Self-update is staged only when safe and not already handled as part of a required server-upgrade MSU swap.

Use /msu status after staging to see the combined plan before restart.

---

🧩 Supported update sources

MSU is built around a configured update source.

mod-list

Best for servers where you want to keep a chosen list of Modrinth projects up to date.

Default file: .minecraft-server-updater/mod-list (one project per line; not a JSON array).

Example:

fabric-api
lithium
c2me-fabric

MSU resolves those projects through Modrinth and checks for compatible builds for the running Minecraft version.

mods-folder

Best for servers that keep a reference folder of known-good jars.

Default folder: .minecraft-server-updater/mods-folder.

MSU reads the reference jars, identifies Modrinth projects where possible, and manages updates from that set.

mrpack

Best for servers based on a Modrinth modpack.

MSU can manage projects from a .mrpack file or a Modrinth pack URL.

advanced.mrpackMode controls behavior:

Mode	Behaviour
exact (default)	Stage the exact pack files and hashes; strict Minecraft / loader checks.
tracking	Treat pack project ids as a managed list and resolve latest compatible builds.

---

🛡️ Safety model

MSU is designed to avoid risky live replacement.

It does not hot-swap running jars

The server keeps using the currently loaded files until restart.

Staged updates are held separately

Downloads and replacement files are prepared in the MSU staging area first.

The wrapper applies updates before boot

When the server is started with the wrapper, MSU applies the staged plan before Fabric starts. Without --wrap, you can still check and stage, but nothing applies on restart.

Rollback support

When a staged plan is applied, MSU can record backup metadata. If boot verification fails, rollback support helps restore the previous working files.

Unknown/custom jars are handled carefully

Unknown jars can be reported and held by local filename policy, but MSU does not treat them as Modrinth-managed or compatibility-checked unless they can be resolved.

Server upgrade preflight

When enabled, MSU checks that managed mods (and required dependencies) look compatible with the target Minecraft version before allowing a server upgrade to stage. Fabric API for the target version is handled as part of the server upgrade path when needed.

Destructive unmanaged mod removal

When enabled for mod-list or mrpack sources, staging may list unmanaged .jar files that would be deleted on apply. Apply is blocked until advanced.allowRemoveUnmanagedMods is true and /msu stage confirm-destructive true has been run on the active staged plan.

Boot recovery and quarantine

After a failed boot, automation and manual staging are blocked until /msu boot clear-failure. If an invalid staged plan is quarantined at apply time, acknowledge it with /msu quarantine acknowledge before staging again.

---

⚙️ Commands

Default command root:

/msu

All /msu commands require operator/admin permission.

Command tree

/msu
├── status
├── reload
├── check
│   ├── mods | server | self | all
├── stage
│   ├── mods | server | self | all
│   ├── confirm-destructive true | false
│   └── cancel
├── rollback [backupId]
├── boot
│   ├── clear-failure
│   └── force-retry
│       ├── current
│       └── <fingerprintId>
├── quarantine
│   ├── acknowledge
│   └── delete confirm
└── config
    ├── reset [param]
    └── set
        ├── source <type> [path]
        ├── automation <mode> [targets]
        ├── interval <minutes>
        ├── debug <on|off>
        ├── server-maintenance <on|off>
        ├── server-upgrade <token>
        ├── mrpack-mode <exact|tracking>
        ├── release-channel <channel> [mod]
        ├── held <on|off> <mod>
        └── required <on|off> <mod>

Quick reference

Command	Purpose
/msu status	Show staged plan, runtime info, config, automation, rollback, unsafe-state warnings, and formatting state.
/msu reload	Reload config from disk and restart automation.
/msu check mods	Check configured mods for the running Minecraft version.
/msu check server	Check server maintenance and optional upgrade readiness.
/msu check self	Check for an MSU self-update.
/msu check all	Run all configured checks (server, mods, and self sections as applicable).
/msu stage mods	Stage mod updates for the running Minecraft version only.
/msu stage server	Stage safe server maintenance or upgrade work.
/msu stage self	Stage an MSU jar replacement.
/msu stage all	Stage all safe selected targets into one combined plan.
/msu stage cancel	Clear the staged plan.
/msu stage confirm-destructive true / false	Acknowledge or clear destructive unmanaged mod removal on the active staged plan.
/msu rollback	Restore the most recent apply backup.
/msu rollback <id>	Restore a named backup.
/msu boot clear-failure	Clear failed-boot record and boot failure streak (does not un-hold mods).
/msu boot force-retry current	Allow automation to retry the current failed-update fingerprint.
/msu boot force-retry <fingerprintId>	Allow automation to retry a specific failed-update fingerprint.
/msu quarantine acknowledge	Acknowledge a quarantined invalid staged plan so automation can continue.
/msu quarantine delete confirm	Delete acknowledged quarantined evidence files.
/msu config reset	Rewrite the config with documented defaults.
/msu config reset <param>	Reset a specific config section (for example source, release-channel).
/msu config set …	Change source, automation, interval, debug, server maintenance, upgrade, mrpack mode, release channel, held mods, or required mods.

Long-running checks may print to the server log; in RCON you may see a background notice — read logs/latest.log for full output.

---

🤖 Automation

MSU can run background checks on a timer.

Automation modes:

Mode	Behaviour
disabled	No background activity.
check	Report only; never stages files.
stage	Checks and stages safe updates; you restart when ready.
install	Checks, stages, then stops the server so the wrapper can apply updates on restart.

Automation targets:

Target	Purpose
mods	Check or stage configured mod source updates (running MC version).
server	Check or stage Fabric server maintenance and optional Minecraft upgrades.
self	Check or stage MSU self-update.

Example:

/msu config set automation stage server mods self
/msu config set interval 360

Use install only when the server is started through the wrapper and you are comfortable with MSU stopping the server for restart-based installation.

Automation is blocked while a failed boot record is active, a quarantined invalid plan is pending acknowledgement, or a failed-update fingerprint has not been cleared or force-retried.

---

🚀 Quick start

1. Put the MSU jar in your server mods/ folder. Modrinth releases use versioned names such as minecraft-server-updater+fabric-26.1.2-0.2.0-beta.4.jar — the filename changes when Minecraft or MSU version changes.
2. Configure your update source.
3. Run a check.
4. Stage available updates.
5. Start the server from the server root (where fabric-server-launch.jar lives) using the wrapper command below.

Wrapper launcher scripts

These are small launcher scripts which replace the existing start scripts in the server root. It picks the first mods/minecraft-server-updater+fabric-*.jar (or mods/minecraft-server-updater.jar) and runs the same wrapper command on every platform.

start.bat (Windows):

@echo off

#set ram requirements here:
set MC_XMX=2G
set MC_XMS=2G

cd /d "%~dp0"
for %%F in ("mods\minecraft-server-updater+fabric-*.jar" "mods\minecraft-server-updater.jar") do (
  java -jar "%%F" --wrap -- java -Xmx%MC_XMX% -Xms%MC_XMS% -jar fabric-server-launch.jar --nogui
  goto :after
)
echo No Minecraft Server Updater jar found in mods\
pause
exit /b 1
:after

start.sh (Linux):

#!/usr/bin/env sh

#set ram requirements here
MC_XMX="${MC_XMX:-2G}"
MC_XMS="${MC_XMS:-2G}"

cd "$(dirname "$0")" || exit 1
for jar in mods/minecraft-server-updater+fabric-*.jar mods/minecraft-server-updater.jar; do
  if [ -f "$jar" ]; then
    exec java -jar "$jar" --wrap -- java -Xmx"$MC_XMX" -Xms"$MC_XMS" -jar fabric-server-launch.jar --nogui
  fi
done
echo "No Minecraft Server Updater jar found in mods/"
exit 1

On Linux: chmod +x start.sh, then ./start.sh.

Example manual update flow

/msu check mods
/msu stage mods
/msu status

Then restart with the wrapper (start.bat, ./start.sh, or the java -jar mods/minecraft-server-updater.jar … line above).

Example Minecraft upgrade flow

/msu config set server-upgrade latest
/msu check server
/msu stage all
/msu status

Read Server safe to stage before staging — if it is false, fix the stated reason (often publish/install a target-compatible MSU build on Modrinth) before stage all.

---

📝 Example configuration

Config file:

config/minecraft-server-updater.json

Example shape:

{
  "debug": false,
  "mods": {
    "sourceType": "mod-list",
    "sourcePath": ".minecraft-server-updater/mod-list",
    "releaseChannel": "any"
  },
  "server": {
    "maintenance": true,
    "upgrade": "off"
  },
  "selfUpdate": {
    "enabled": true
  },
  "automation": {
    "mode": "disabled",
    "intervalMinutes": 360,
    "targets": []
  },
  "advanced": {
    "unknownModPolicy": "error",
    "modUpgradePolicy": "warn",
    "readinessMode": "all",
    "mrpackMode": "exact",
    "preflightBeforeServerUpgrade": true
  }
}

Common config commands:

/msu config set source mod-list
/msu config set source mods-folder
/msu config set source mrpack modpack.mrpack
/msu config set server-maintenance on
/msu config set server-upgrade latest
/msu config set automation stage server mods self
/msu config set mrpack-mode exact
/msu config set debug on

If automation mode is check, stage, or install but targets is empty, automation runs with nothing to do until you add targets.

---

🎨 Console formatting

MSU includes styled output support for its own server-log lines.

Advanced config:

"betterFabricConsoleFormatting": "auto"

Available values:

Value	Behaviour
auto	Default styled MSU output when console colour is allowed.
on	Force styled MSU output when colour is allowed.
off	Always use plain MSU server-log output.

If Better Fabric Console is installed separately, MSU avoids double-rendering and lets BFC handle Minecraft formatting.

---

❌ What MSU does not do

MSU is intentionally conservative.

It does not:

• Replace live jars while the server is running
• Treat unknown/custom jars as Modrinth-managed projects
• Apply staged updates without the wrapper
• Magically verify compatibility for non-Modrinth files
• Use fuzzy Modrinth search to resolve configured project names
• Mix “routine mod updates on today’s version” with “server upgrade staging” in a single check — read server and mod sections separately

---

Recommended workflow

Routine mod updates (same Minecraft version):

/msu check mods
/msu stage mods
/msu status

Restart with the wrapper when ready.

Planned Minecraft upgrade:

/msu check server
/msu check mods
/msu stage all
/msu status

Confirm Server safe to stage: true and review the combined plan before restart.

Scheduled staging:

/msu config set automation stage mods
/msu config set interval 360

Unattended install workflows:

/msu config set automation install server mods self

Use install mode only when the server is started through the wrapper and you are happy for MSU to stop the server for restart-based installation.

---

Why use MSU?

MSU gives Fabric server owners a controlled update workflow:

• See what needs updating before anything changes
• Get clear reasons when staging is blocked
• Stage files safely without touching live jars
• Apply updates before boot through the wrapper
• Keep server files and Modrinth-managed mods in sync
• Automate routine checks
• Recover with rollback support if an applied update causes problems