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:

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.

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

Safe-to-stage lines

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.

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:

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.

Default command root:

/msu

All /msu commands require operator/admin permission.

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

MSU can run background checks on a timer.

Automation modes:

Automation targets:

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.

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.

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 debug on

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

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

Advanced config:

"betterFabricConsoleFormatting": "auto"

Available values:

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

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