Change the server software

The Software tab, under More on the server's page, 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. Under it, on a plugin server, the Cross-version play switch keeps ViaVersion and ViaBackwards on the server, and it starts on: Let players on other Minecraft versions join explains it.

1. In the dashboard, go to App Deployment 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. A move between a plugin server, Fabric and NeoForge keeps it on, and the next start installs Geyser and Floodgate for the new software. Software that cannot load plugins loses the two plugins of cross-version play until it moves back to a plugin server.
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. On a free server, a start waits until the change finishes: a start already in the queue keeps its place, and Start answers A software change is running on this server. Start it again when the change finishes.

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.

When the connection to the server drops while a job copies a file, the job waits and tries again, up to 8 times over about 20 minutes. If the connection still drops, the job fails with the last error.

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.

The server is out of disk space, so the files could not be copied to it.

The new software does not fit on the server's disk, so the job stops at once instead of trying again. Free some space (The disk is full), then start the change again.

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. Try again later.

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, variables (every value the software asks for, each with name, default and required) and required_variables (the ones it cannot install without). A Git address is optional: without one the server starts empty. With one on GitHub or GitLab, the server gets a Releases tab to update it from the repository (Update a server from its git repository).

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, newest first. Each has a key, which is its loader version (for example 0.16.9), and also project_version, build_number and experimental. Many builds of one version share the same build_number, so name a build by its key.

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.