# Change the server software

> Switch your server to other software, or to another version of the same software, and follow the install job.

Source: https://docs.coritan.com/managed-containers/software/

In the dashboard:

- /dashboard/servers/…/software: https://www.coritan.com/dashboard/servers

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](/managed-containers/software/plugins-and-mods/).
- **Installed addons** turns them on or off, updates and removes them: see [Manage installed addons](/managed-containers/software/installed-addons/).
- **Java** sets the memory, startup flags and Java version: see [Change Java settings](/managed-containers/software/java-settings/).
- **Resource pack** and **Safe mode** are covered in [Set a server resource pack](/managed-containers/software/resource-pack/) and [Start a server in safe mode](/managed-containers/software/safe-mode/).
- **Packs** replaces the last four on a Bedrock server: see [Manage Bedrock packs](/managed-containers/software/bedrock-packs/).

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

## Before you begin

- Take a [snapshot](/managed-containers/snapshots/) 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](/managed-containers/users/#with-the-api).

## Read the current software

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](/managed-containers/software/bedrock-crossplay/) explains it.

## Switch software or change the version

1. In the [dashboard](https://www.coritan.com/dashboard/servers), 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.

## What the change does

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](/managed-containers/software/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](/managed-containers/console/) when the job shows `Succeeded`.

## Follow and cancel jobs

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.

## Result

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.

## Troubleshooting

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

## Related

- [Install plugins, mods and modpacks](/managed-containers/software/plugins-and-mods/)
- [Change Java settings](/managed-containers/software/java-settings/)
- [Take a server snapshot](/managed-containers/snapshots/)
- [Server limits and rate limits](/managed-containers/limits/)

## With the API

`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:

```bash
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"}'
```

| Field | What it holds |
| --- | --- |
| `target_key` | The catalogue entry's `key`. Required. |
| `version` | A `version_id`, or `latest` (the default). |
| `runtime_template_slug` | The Java runtime. Leave it out for the recommended one. |
| `build` | A loader build number. Leave it out for the newest build. |
| `mode` | `keep` (the default) or `wipe`. |
| `confirm_server_name` | The server's name. Required with `wipe`. |
| `variables` | Values the software needs, when `required_variables` names any. |

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

| Request | What it does |
| --- | --- |
| `GET /software/installs` | Lists the server's software jobs, newest first, up to 50. Add `status=active` for the queued and running ones, or any single status. |
| `GET /software/installs/{install_uuid}` | Returns one job. |
| `POST /software/installs/{install_uuid}/cancel` | Cancels a queued or running job and returns it. A finished job answers `409`, such as `Install is already succeeded`. |
| `POST /software/installs/{install_uuid}/retry` | Queues a finished install again with the same settings and returns the new job. A job that is still running answers `409` with `That install is still in progress`. |

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

## API

- `GET /api/v1/client/servers/{uuid}/software/context`: Return loader/game-version context for marketplace tab gating (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-context)
- `GET /api/v1/client/servers/{uuid}/software/catalog`: Server software the machine can be switched to, grouped for display (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-catalog)
- `GET /api/v1/client/servers/{uuid}/software/catalog/{key}/versions`: Installable versions for one catalog entry, with runtime recommendations (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-catalog-key-versions)
- `GET /api/v1/client/servers/{uuid}/software/catalog/{key}/versions/{version}/builds`: Publisher builds of one game version: the loader versions for Fabric/Forge (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-catalog-key-versions-version-builds)
- `POST /api/v1/client/servers/{uuid}/software/change`: Switch the server to different software, or a different version of it (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-post-api-v1-client-servers-uuid-software-change)
- `GET /api/v1/client/servers/{uuid}/software/installs`: List recent software install jobs for a server (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-installs)
- `GET /api/v1/client/servers/{uuid}/software/installs/{install_uuid}`: Get a single software install job (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-installs-install-uuid)
- `POST /api/v1/client/servers/{uuid}/software/installs/{install_uuid}/cancel`: Cancel a queued software install (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-post-api-v1-client-servers-uuid-software-installs-install-uuid-cancel)
- `POST /api/v1/client/servers/{uuid}/software/installs/{install_uuid}/retry`: Queue a fresh install job with the same parameters as a failed one (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-post-api-v1-client-servers-uuid-software-installs-install-uuid-retry)