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 or Forge 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.

• Fabric: Fabric Loader and fabric-server-launch.jar when enabled. Fabric API for the running version is handled by mod checks/staging. The vanilla server.jar only changes when Minecraft changes version.
• Forge: latest Forge for the running Minecraft version (installer-generated shim, run.bat / run.sh, and libraries/…/win_args.txt or unix_args.txt). The vanilla jar lives under libraries/net/minecraft/server/<mc>/, not as a root server.jar.

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 root server.jar, or Forge’s library jar for that version)
• Fabric launcher / loader or Forge installer output for the target version
• Fabric API for the target version on Fabric (shown under server update candidates, not as a normal mod-list update)
• Optional mod preflight for the upgrade target when enabled
• A target-compatible MSU jar when Minecraft version changes (Fabric and Forge MSU files are published separately)

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. Use the Fabric file on Fabric and the Forge file on Forge.

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.
• On Forge, the server section names Minecraft / Forge (for example 26.2 / 65.1.3) instead of Fabric Loader / Fabric API.
• 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

On Forge, list Forge-loader Modrinth projects the same way (one slug, id, or exact title per line).

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 or Forge starts. Without --wrap (Fabric) or --wrap-forge (Forge), 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. On Fabric, 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.

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

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 (--wrap or --wrap-forge) 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.

1. Put the matching MSU jar in mods/. Fabric: minecraft-server-updater+fabric-<msu>.jar. Forge: minecraft-server-updater+forge-<msu>.jar. Do not mix both jars on one server. Current names do not embed the Minecraft version; list supported game versions on the Modrinth file.
2. Configure your update source.
3. Run a check.
4. Stage available updates.
5. Start from the server root with the wrapper for your loader (replace stock run.bat / run.sh on Forge).

Fabric wrapper

Start from the directory that contains fabric-server-launch.jar. These scripts pick the first mods/minecraft-server-updater+fabric-*.jar (or mods/minecraft-server-updater.jar).

start.bat (Windows):

@echo off

REM 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.

Forge wrapper

Forge does not use --wrap -- java -jar …. --wrap-forge finds the installed coordinate under libraries/net/minecraftforge/forge/<minecraft>-<forge>/ and launches the same way stock run.bat does:

java @user_jvm_args.txt @libraries/net/minecraftforge/forge/<mc>-<forge>/win_args.txt --nogui

Put RAM and other JVM flags in user_jvm_args.txt. Extra arguments after --wrap-forge (usually --nogui) are Minecraft program args. Do not java -jar forge-*-shim.jar yourself; leftover installer/shim jars in the server root are not what the wrapper runs.

start.bat (Windows):

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

start.sh (Linux):

#!/usr/bin/env sh
cd "$(dirname "$0")" || exit 1
for jar in mods/minecraft-server-updater+forge-*.jar mods/minecraft-server-updater.jar; do
  if [ -f "$jar" ]; then
    exec java -jar "$jar" --wrap-forge --nogui
  fi
done
echo "No Minecraft Server Updater jar found in mods/"
exit 1

After a Forge Minecraft/Forge bump, the wrapper resolves the new win_args.txt / unix_args.txt on the next start so launch does not stay pointed at the previous coordinate.

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 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.

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

Advanced config:

"betterFabricConsoleFormatting": "auto"

Available values:

If Better Fabric Console is installed separately on Fabric, MSU avoids double-rendering and lets BFC handle Minecraft formatting. Forge uses MSU’s embedded converter. Wrapped servers keep colour when the wrapper sets -Dterminal.ansi=true.

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 (--wrap or --wrap-forge)
• 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
• Run a Fabric MSU jar on Forge, or a Forge MSU jar on Fabric