# The server used all of its container memory and was killed

The container that runs the Minecraft server went over its memory limit, so the system ended the server at once, without saving.

- Code: `container_oom_killed`
- Severity: fatal
- Category: Performance
- Server types: Every server type
- Page: https://failures.perland.online/failures/container_oom_killed/

## Example log

```text
$ docker inspect --format '{{json .State}}' survival-mc
{
  "Status": "exited",
  "Running": false,
  "OOMKilled": true,
  "ExitCode": 137,
  "StartedAt": "2026-11-03T18:02:41.390115Z",
  "FinishedAt": "2026-11-03T21:47:09.402118Z"
}
```

## Parameters

| Parameter | Meaning |
| --- | --- |
| `memoryLimit` | The container's memory limit when Docker reports one, written like 2G or 512M. |

## Log lines this page covers

- `"OOMKilled": true`

## What it means

A container runs with a memory limit (Docker's `--memory`, or `mem_limit` in a compose file). It counts everything the server's processes use: the Java heap and all the memory Java needs besides it. When the server goes over the limit, the Linux kernel kills the process at once. Nothing is saved, nothing is printed in the server's log, and the container stops with exit code 137.

Docker records the kill on the container: `OOMKilled` is `true` in `docker inspect`. That flag is what this issue reads, not a log line. Exit code 137 alone is not enough: Docker also uses it when a server is killed because it took too long to stop.

## Why it happens

- **The Java heap is set too close to the limit.** Java uses memory outside the heap too: loaded code (metaspace), threads, network buffers and the native libraries of some mods. A heap of 4 GB in a 4 GB container leaves nothing for them.
- **The server needs more memory than it has.** A modpack, many plugins or many players outgrew the limit.
- **Memory outside the heap grows.** Some mods and plugins allocate native memory that Java's heap limit does not cap.
- **A heap size set by hand** (`-Xmx`, `MEMORY`) that ignores the container's limit.

Unlike `out_of_memory`, Java itself did not fail here: the system stopped the whole process from outside.

## How to fix

1. Raise the container's memory limit, then start the server again.
2. Keep the heap below the limit. A common rule is to leave at least 512 MB, or about 15% of the limit, outside the heap. With the itzg/minecraft-server image, set `MEMORY` below the container's limit rather than equal to it.
3. If you set `-Xmx`, `MEMORY` or other memory options yourself, check them against the limit.
4. If the server was killed after running for a long time, look for a plugin or mod whose memory keeps growing, and remove or update it.
5. When the server is back, check that the world is as expected: a kill loses whatever was not saved yet.

## In Perland

The issue appears in the server's Diagnosis tab with the memory limit the server had, and links to the server's resources, where you can give it more memory. Perland derives the Java heap from the container's limit and leaves the larger of 512 MB and 15% of it for the rest of Java, so this usually means the server needs more memory overall, or that a heap size set by hand in the server's settings leaves too little room.

## References

- [Docker: resource constraints (memory)](https://docs.docker.com/engine/containers/resource_constraints/)
- [Docker Minecraft Server: JVM options and memory](https://docker-minecraft-server.readthedocs.io/en/latest/configuration/jvm-options/)