# Change Java settings

> Set the Java memory, startup flags and Java version your Minecraft Java server starts with.

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

In the dashboard:

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

The **Java** panel on a server's **Software** tab sets three things a Java server starts with: how much memory Java may use for the game (the *heap*), the startup flags that tune Java's garbage collector, and the Java version. Saving never restarts the server. Your changes apply the next time it starts.

## Before you begin

- The panel is there for servers that run on Java. A Bedrock server does not have it.
- On a server someone shared with you, reading the panel needs `startup.read` and saving needs `startup.update`. The dashboard's permission list offers neither, so the owner can grant them only [through the API](/docs/managed-containers/users/#with-the-api).
- Each save counts towards the limit of 8 software actions from one account on a server in 10 minutes.

To open the panel:

1. In the [dashboard](https://www.coritan.com/dashboard/servers), go to **Container Apps** and open the server, then the **Software** tab.
2. Select **Java**.

The **Java settings** card shows the Java version the server runs, such as `Java 21`, next to its title.

## Set the Java memory

Java needs memory beyond the heap, and the server is stopped if it runs out of memory altogether. So the heap starts below your plan's memory, and you can raise it:

| Setting | Value |
| --- | --- |
| Default on a paid plan | 80% of the plan's memory, rounded down to 16 MB |
| Default on a free server | 2048 MB |
| Lowest | Half the plan's memory, rounded down to 256 MB, and never less than 1024 MB |
| Highest | The plan's memory |

For example, on a plan with 4096 MB the default is 3264 MB, and the heap can go from 2048 MB to 4096 MB.

1. Under **Java memory**, move the slider. It moves in steps of 256 MB, and it also stops at the default and at the full plan.
2. Or select the button under the slider that uses the default or the full plan.
3. Or type a number of megabytes in **Exact size**.
4. Select **Save Java settings**.

A badge next to **Java memory** says `Default`, `Full plan` or `Custom`.

> [!WARNING]
> With the heap at the full plan, Java has little room left for everything else it needs, and a busy server can run out of memory and be stopped. If that happens, go back to the default.

When your plan's memory changes, or a free server moves to a paid plan, the heap goes back to the new plan's default.

When the heap reaches 12 GB, four of the startup flags that size the young generation switch to larger values. The panel says so under **Exact size**.

## Choose the startup flags

The startup flags are Aikar's flags, a set widely used to keep Minecraft's garbage collection smooth. All of them are on by default. You can turn off the ones you do not want, but you cannot add flags of your own.

1. Under **Startup flags**, choose **Recommended** for every flag, **Off** for none, or **Custom**.
2. To see or change single flags, select **Show flags**. Ticking or clearing a flag switches to **Custom**.
3. Select **Save Java settings**.

Next to the choice, the panel counts the flags that are on, such as `19 of 19 flags on · Java 21`.

A flag that your Java version does not accept is greyed out, with the reason, such as `Needs Java 16 or newer; this server runs Java 11.` *Unlock experimental options* is added automatically while an experimental flag is on.

Startup flags are there for Minecraft Java software only. On other Java software the panel says `Startup flags are offered to Minecraft Java software only.`

## Change the Java version

1. Choose a Java in **Java version**. The list puts the newest first and marks the current one `(current)`. Next to each Java it names the Minecraft releases that Java is for.
2. Select **Save Java settings**.

| Java | Minecraft releases |
| --- | --- |
| Java 21 and newer | 1.20.5 and newer |
| Java 17 | 1.17 to 1.20.4 |
| Java 8 | 1.16.5 and older |

The server does not start on the wrong Java. When you change the Minecraft version under [Server software](/docs/managed-containers/software/), choose the Java there in the same step.

## See the startup command

Select **Show startup command** to see the full command the next start runs, with the heap and flags in place. Select **Copy startup command** to copy it.

## Reset the heap and flags

**Reset to defaults…** appears once you have changed the heap or the flags.

1. Select **Reset to defaults…**.
2. Select **Reset Java settings**.

The heap and the flags go back to the plan's defaults on the next start. The Java version stays as it is.

## Result

A message says `Java settings saved. They apply on the next start.`, or `Heap and startup flags reset to their defaults. They apply on the next start.` after a reset. Restart the server from the [console](/docs/managed-containers/console/) to use them.

## Troubleshooting

**No Java settings here**
: The server cannot use the panel. `This server does not run on Java, so there is no heap or startup flags to set.` means it runs other software. `The startup command sets its own heap; ask support to change it.` means its startup command names a fixed heap. Ask [support](/docs/support/) to change it.

**Could not load the Java settings**
: On a server shared with you, you need `startup.read`. Otherwise, select **Try again**.

`Enter a whole number of megabytes from 2048 to 4096.`
: The number in **Exact size** is outside what your plan allows. The message gives your plan's range.

**Could not save the Java settings**
: The panel shows the reason, such as a flag your Java version does not accept. Change that setting and save again.

The server does not start after a change
: Check that the Java version fits the Minecraft version, using the table above. Then check the [console](/docs/managed-containers/console/) for the error.

The server stops because it ran out of memory
: Lower the heap to the default, or [move to a larger plan](/docs/billing/change-plan/).

`Too many requests for this action. Please wait and try again.`
: A server accepts 8 software actions from one account in 10 minutes. The response says how many seconds to wait.

## Related

- [Change the server software](/docs/managed-containers/software/)
- [Use the console and power controls](/docs/managed-containers/console/)
- [Server settings](/docs/managed-containers/settings/)

## With the API

`GET /api/v1/client/servers/{uuid}/software/jvm` returns what the panel shows:

`supported`
: `false` when the server cannot use the panel, with the reason in `unsupported_reason`.

`memory`
: `supported` (whether the heap can change), `heap_mb`, `default_mb`, `min_mb`, `max_mb`, `stops` (the slider's positions), `is_default`, `free` and `size_tier` (`small`, or `large` from 12 GB).

`flags`
: `supported`, `java_major`, `selected` (the ids that are on), `defaults`, `is_default` and `catalog`. Each catalog entry has an `id`, `label`, `description`, `group`, `flag` (what it adds to the command), `available`, `unavailable_reason`, `experimental` and `selected`.

`runtime`
: `supported`, the current `slug` and `java`, and `options`, each with a `slug`, `java` and `name`.

`effective_command`
: The startup command the next start runs.

`PATCH` the same path with any of these fields:

| Field | What it does |
| --- | --- |
| `heap_mb` | The heap, a whole number of megabytes from `min_mb` to `max_mb`. |
| `flags` | The ids of the flags to turn on, from `catalog`. `[]` turns them all off. |
| `runtime_template_slug` | A `slug` from `runtime.options`, such as `java-21`. |
| `reset` | `true` drops the stored heap and flags, as **Reset to defaults…** does. The other fields are then ignored. |

```bash
curl -X PATCH https://api.coritan.com/api/v1/client/servers/$SERVER/software/jvm \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"heap_mb": 3072, "flags": ["g1gc", "parallel-ref-proc", "max-gc-pause", "disable-explicit-gc"]}'
```

The response is the new view, as `GET` returns it, plus `synced`, which says whether we could pass the new settings on straight away. When it is `false`, they still apply at the next start. To go back to the recommended flags but keep your heap, send the `defaults` list as `flags`.

| Flag id | Label | Adds |
| --- | --- | --- |
| `vector-api` | Vector API (SIMD) | `--add-modules=jdk.incubator.vector`, on Java 16 and newer |
| `g1gc` | G1 garbage collector | `-XX:+UseG1GC` |
| `parallel-ref-proc` | Parallel reference processing | `-XX:+ParallelRefProcEnabled` |
| `max-gc-pause` | Pause target 200 ms | `-XX:MaxGCPauseMillis=200` |
| `unlock-experimental` | Unlock experimental options | `-XX:+UnlockExperimentalVMOptions` |
| `disable-explicit-gc` | Ignore System.gc() | `-XX:+DisableExplicitGC` |
| `g1-heap-waste` | Heap waste 5% | `-XX:G1HeapWastePercent=5` |
| `g1-mixed-gc-count` | Mixed collection target 4 | `-XX:G1MixedGCCountTarget=4` |
| `ihop` | Start marking at 15% | `-XX:InitiatingHeapOccupancyPercent=15`, on Java 28 and older |
| `g1-mixed-live-threshold` | Mixed collection live threshold 90% | `-XX:G1MixedGCLiveThresholdPercent=90` |
| `g1-rset-updating` | Remembered-set updating 5% | `-XX:G1RSetUpdatingPauseTimePercent=5` |
| `survivor-ratio` | Survivor ratio 32 | `-XX:SurvivorRatio=32` |
| `perf-disable-shared-mem` | No perf shared memory | `-XX:+PerfDisableSharedMem` |
| `max-tenuring` | Tenuring threshold 1 | `-XX:MaxTenuringThreshold=1` |
| `aikar-marker` | Aikar's flags marker | `-Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true` |
| `g1-new-size` | Young generation minimum | `-XX:G1NewSizePercent=30`, or `40` from 12 GB |
| `g1-max-new-size` | Young generation maximum | `-XX:G1MaxNewSizePercent=40`, or `50` from 12 GB |
| `g1-heap-region` | Heap region size | `-XX:G1HeapRegionSize=8M`, or `16M` from 12 GB |
| `g1-reserve` | Heap reserve | `-XX:G1ReservePercent=20`, or `15` from 12 GB |

`g1-mixed-live-threshold`, `g1-new-size` and `g1-max-new-size` are experimental: when any of them is on, `unlock-experimental` is added for you. A flag the startup command already carries is not added twice.

A request the server cannot take answers `400` with the reason, such as `Send heap_mb, flags, runtime_template_slug or reset`, `heap_mb must be between 2048 and 4096 MB on this plan`, `Unknown startup flag 'xyz'; only the listed flags can be used`, `Vector API (SIMD): Needs Java 16 or newer; this server runs Java 11.` or `No Java runtime called 'java-99' is available`. A server that is not on a Java runtime answers `This server does not run on a Java runtime; changing it is a software change`: change it under [Server software](/docs/managed-containers/software/#with-the-api) instead.

Reading needs `startup.read` and changing needs `startup.update`.

## API

- `GET /api/v1/client/servers/{uuid}/software/jvm`: The heap slider and the allowlisted startup flags, as the panel shows them (https://www.coritan.com/docs/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-jvm)
- `PATCH /api/v1/client/servers/{uuid}/software/jvm`: Move the heap, pick startup flags from the catalog, or reset both (https://www.coritan.com/docs/api/reference/client/container-apps/servers-software/#op-patch-api-v1-client-servers-uuid-software-jvm)