Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A Java container dies at start with 'insufficient memory' or errno=12

ErrorThere is insufficient memory for the Java Runtime Environment to continue.

Short answer

The JVM asked the operating system for more memory than the container is allowed to use. The heap flags are the first suspect: a fixed -Xmx or -Xms larger than the container limit fails at once. Next come native memory that the heap setting does not cover (metaspace, thread stacks) and a limit that is simply too small.

  • Applies to OpenJDK 21, Docker Engine 27, Spring Boot 3, Tomcat 10.1
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the memory limit Docker gave the container with the heap flags the JVM was started with, and let the JVM print what it detected from the container.

    docker inspect --format 'limit={{.HostConfig.Memory}}' my-container
    docker run --rm --memory=512m my-image java -Xlog:os+container=trace -version
  2. 2Match what you see, then jump to its fix

    1. 1The crash comes in the first seconds and the flags (or JAVA_OPTS) show a heap size close to or above the --memory valueA fixed -Xmx or -Xms is larger than the container limitFix
    2. 2The heap fits, yet the JVM still fails when it grows or creates many threadsNon-heap memory pushes the process over the limitFix
    3. 3Even a small heap fails, or several containers fail at the same timeThe container limit is too small, or the host has no memory leftFix

What does the error look like?

  • There is insufficient memory for the Java Runtime Environment to continue.
  • os::commit_memory failed; error='Not enough space' (errno=12)
  • Native memory allocation (mmap) failed to map

Cause 1 of 3

A fixed -Xmx or -Xms is larger than the container limit

1Check

Look for -Xmx and -Xms in the command, the Dockerfile and any environment variable that feeds the JVM. A hard-coded heap ignores the container limit.

docker inspect --format '{{.Config.Env}} {{.Config.Cmd}} {{.Config.Entrypoint}}' my-container

2Fix

Remove the fixed sizes and let the JVM size the heap from the container limit. The default maximum heap is only 25 percent of the memory it detects, so raise it with a percentage if you need more, and leave room for non-heap memory.

docker run --memory=1g my-image \
  java -XX:MaxRAMPercentage=60 -jar app.jar

3Verify

Start the container and watch it stay up past the startup phase.

docker run -d --name my-container --memory=1g my-image java -XX:MaxRAMPercentage=60 -jar app.jar
docker logs --tail 20 my-container

Confirmed by docs.oracle.com

Did this fix it?

Cause 2 of 3

Non-heap memory pushes the process over the limit

1Check

The heap is only part of the process. Class metadata (metaspace) has no limit by default, and each thread takes a stack of 1024 KB on Linux x64 by default. Many threads or many loaded classes add up outside the heap.

docker exec my-container sh -c 'ls /proc/1/task | wc -l'

2Fix

Cap metaspace, reduce the thread stack size and thread counts where the app allows, and keep the heap percentage lower to leave room.

java -XX:MaxRAMPercentage=50 -XX:MaxMetaspaceSize=256m -Xss512k -jar app.jar

3Verify

Run the app under its normal load for a few minutes and check it is still running.

docker stats --no-stream my-container

Confirmed by docs.oracle.com

Did this fix it?

Cause 3 of 3

The container limit is too small, or the host has no memory left

1Check

--memory is a hard cap, and without swap a container that crosses it is killed by the kernel. Compare the limit with what the host has free.

docker inspect --format 'mem={{.HostConfig.Memory}} swap={{.HostConfig.MemorySwap}}' my-container
free -m

2Fix

Give the container a higher --memory value, or stop other containers to free host memory. Setting --memory-swap equal to --memory means no swap for the container.

docker run --memory=1g --memory-swap=1g my-image

3Verify

Start it again and check it runs.

docker ps --filter name=my-container

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Set the container limit and the JVM sizing together, and write both in the same compose file.
  • Use percentages (MaxRAMPercentage) instead of a fixed -Xmx so the JVM follows the limit.
  • Leave a share of the limit for metaspace, stacks and the JVM itself; do not give the heap all of it.
  • Log container detection once with -Xlog:os+container=trace when you change limits.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.