Change the server software

The Software tab shows what your server runs and switches it to other software, or to another version of the same software. A change is a reinstall that runs as a job: you choose whether to keep the server's files or start clean. The tab's other panels add and manage what runs on top of the software:

• Marketplace installs plugins, mods, datapacks and modpacks: see Install plugins, mods and modpacks.
• Installed addons turns them on or off, updates and removes them: see Manage installed addons.
• Java sets the memory, startup flags and Java version: see Change Java settings.
• Resource pack and Safe mode are covered in Set a server resource pack and Start a server in safe mode.
• Packs replaces the last four on a Bedrock server: see Manage Bedrock packs.

The panels a server shows depend on its software. Java appears only on software that runs on Java, for example.

• Take a snapshot first. Start clean deletes every file on the server, and moving a world to a newer game version can change it for good, even with Keep my files.
• The change stops the server, so tell your players.
• On a server someone shared with you, a change needs settings.reinstall as well as the Install software permission. The dashboard's permission list has no option for settings.reinstall, so the owner can grant it only through the API.

The Current software card at the top of the tab shows what the server runs now:

Software

The software's name, such as Paper or Fabric.

Version

The game version, such as 1.21.4.

Edition

Bedrock, shown only for a Bedrock server.

Loader

The loader, with its build when you chose one.

Java

The Java version the server runs on.

Jar

The file the server starts, such as server.jar.

Modpack

The modpack you installed from the Marketplace, if any.

On a Java server that can take Bedrock players, the card also has the Bedrock crossplay switch. Let Bedrock players join a Java server explains it.

1. In the dashboard, go to Container Apps and open the server, then the Software tab. The Server software panel opens first.
2. Under Choose the software to run, select the software. To move to another version of what you run now, select the entry marked Current. Search software filters the list. Entries marked Experimental or Deprecated install like the others, but their publishers do not recommend them for a main server.
3. Choose a version. The newest 12 show first: select the button under them for the rest, or type in Search versions. Select Show snapshots and unsupported builds to list snapshots and versions we do not offer by default.
4. For Fabric, Quilt, Forge and NeoForge, choose a Loader build, or leave it on Latest build. A modpack names the loader version it needs.
5. Choose the Java runtime. The field's hint names the runtime we recommend for that version. You cannot choose a Java version older than the one the game version needs.
6. Choose what happens to the files:
   • Keep my files swaps the server jar, the startup command and the Java runtime. Worlds, plugins and configs stay.
   • Start clean deletes every file on the server first, then installs the software fresh.
7. Select Switch software, or Change version when you stay on the same software. With Start clean, the button is Wipe and install…: type the server's name to confirm, then select Wipe and install.

When you switch to software with a different loader and keep your files, plugins and mods written for the old loader do not load on the new one. They stay on the server, so you can remove them or find new versions afterwards.

The job runs in this order:

1. It waits for any other software job on the server to finish first.
2. It stops the server. With Keep my files, we ask the server to stop and force it after a minute. With Start clean, we force it straight away.
3. With Start clean, it deletes the server's files and our records of what the Marketplace installed.
4. It applies the new software's startup command, Java runtime and ports. Software that cannot run Bedrock crossplay has it turned off.
5. It downloads and installs the software, then checks that the file the server starts is on disk.

While the new software installs, the server shows Installing. The job does not start the server for you: start it from the console when the job shows Succeeded.

Every software job on the server appears in a card above the panels: changes, installs and updates. While a job runs, the card counts the running jobs, such as 1 job running, and updates every few seconds. When nothing runs, the card is Recent jobs and shows the last three.

Each row shows the job, the version it asked for, its status and its current step, such as Stopping or Installing, with a progress bar. A row marked Stalled has not reported progress for a while; we pick it up again automatically.

• To stop a job that is queued or running, select Cancel job. A queued job never starts. A running job stops at its next step.
• To run a failed install again, select Try again.

If a change fails or is cancelled after the old software was removed, we check the server's files. When the new software is not there, we retry the install ourselves.

A message confirms the change was queued, and the job appears in the jobs card. Its status moves from Queued to Running, then to Succeeded, Succeeded with warnings, Failed or Cancelled. After a change, the Current software card shows the new software and version.

Try again fails on a software change

It fails with mode must be one of: add, replace, update, because Try again handles only installs at the moment. Choose the software and version again and start a new change.

Another software job is running. This one queues behind it.

The form shows this while another job runs. Your change waits for it and then runs alone.

The installed software does not match the plan

The software on disk uses a different loader from the software the server was set up with, for example after you installed a Fabric modpack on a Paper server. Choose the software you want under Server software so the startup command, the Java runtime and the addon folders match.

The startup command points at a different jar than the one installed. Switching version under Server software rewrites it.

Change to the version you want, even the one you run now with another loader build, to fix the startup command.

Type the server name to confirm a wipe and reinstall

The name you typed did not match. Type the server's name exactly as the dashboard shows it.

Minecraft Paper has no installable versions right now.

The software's publisher did not answer with any versions. Try again later, or choose a specific version.

Wings reported the install script failed, so the new software is not on disk.

The install failed on the server. The message ends with the last lines of the install's output. We retry the install automatically.

Too many requests for this action. Please wait and try again.

A server accepts 8 software actions from one account in 10 minutes. Changes, installs and updates all count. The response says how many seconds to wait.

The change answers 423

We have locked the server for review. The message tells you to reply to the support ticket we opened.

• Install plugins, mods and modpacks
• Change Java settings
• Take a server snapshot
• Server limits and rate limits

GET /api/v1/client/servers/{uuid}/software/context returns what the server runs: specialization_slug and specialization_name, mcjars_type, loader, loader_family, loader_build, game_version, edition, runtime_template_slug, runtime_java, jar_filename, supported_kinds and install_dirs. It also carries needs_software_change, startup_mismatch, bedrock_bridge, safe_mode, active_installs and install_busy, which is true while a job that must run alone is queued or running.

GET /api/v1/client/servers/{uuid}/software/catalog lists the software the server can switch to. groups holds each heading's key, label and items. An item's key, such as minecraft-paper, is what a change sends. It also has name, description, loader, experimental, deprecated, is_current and required_variables.

GET /software/catalog/{key}/versions lists one entry's versions, newest first. Each has version_id, name, required_java, supported and recommended_runtime_slug. runtimes lists the Java runtimes by slug and name, and current_version is the version the server runs now. Add include_unsupported=true for snapshots and unsupported versions, and limit from 1 to 500 (default 200).

GET /software/catalog/{key}/versions/{version}/builds lists the loader builds of one version for Fabric, Quilt, Forge and NeoForge, each with a build_number.

Queue a change:

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/software/change \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_key": "minecraft-paper", "version": "1.21.4", "runtime_template_slug": "java-21", "mode": "keep"}'

The response is the job, with kind set to software_change. Sending a change while the same change is queued or running returns that job. A refusal answers 400 with the reason in detail, and an unknown key answers Specialization minecraft-papr not found.

The paths are relative to /api/v1/client/servers/{uuid}. A job has uuid, kind, identifier, mode, requested_version and resolved_version, status, stage, progress from 0 to 100, error and error_code when it fails, stalled, cancel_requested, and created_at, started_at and finished_at. detail holds what the job did, including warnings when it finished with some.

On a server shared with you, reading needs software.read, a change needs settings.reinstall and software.install, and cancelling or retrying needs software.install.