JVM memory flags in containers: best practices explained

JVM memory flags in containers: best practices explained

Running Java applications in containers forces us to rethink how we configure JVM memory. Ten years ago, we'd set -Xmx2g and call it done, but containers operate under fundamentally different constraints. Modern JVMs have caught up to this reality, and understanding how to leverage container-aware memory configuration can be the difference between smooth deployments and midnight OOMKilled incidents.

Modern JVMs respect cgroup limits

For years, the JVM had no awareness of Linux cgroups. When Docker assigned a container 512 MB of memory, the JVM would still read the underlying host's total RAM and make allocation decisions based on that figure. This mismatch led to containers getting killed by the OS while the JVM thought it had plenty of headroom.

Starting with Java 9, and refined significantly in Java 10+, the JVM recognizes cgroup v1 and v2 limits. Modern Spring Boot applications running on Java 11 or later can detect their container's memory ceiling automatically. This means the JVM queries /sys/fs/cgroup/memory/memory.limit_in_bytes (cgroup v1) or the memory.max controller (cgroup v2) to understand its true resource constraints.

You can verify this is working by checking the JVM's output at startup. When you run a containerized application with verbose GC logging enabled, you'll see lines like:

Memory: 4k page, physical 1048576k(987654k free), swap 0k(0k free)
MaxHeapSize: 268435456 (256.0MB), MaxMetaspaceSize: 4294967296 (4096.0MB)

The MaxHeapSize should correlate with your container's memory limit, not the host machine's RAM. If it doesn't, you're likely running an older Java version or your container orchestration platform isn't setting cgroup limits correctly.

Use -XX:MaxRAMPercentage=75 instead of -Xmx

This is the critical shift in how we configure containerized Java applications. Instead of hardcoding heap size with -Xmx1024m, we tell the JVM to size itself as a percentage of available container memory using -XX:MaxRAMPercentage=75.

Here's why this matters: when your container has 1 GB of memory limit, a static -Xmx756m works until someone resizes the container to 2 GB. Now you're wasting 1.2 GB of available memory. With -XX:MaxRAMPercentage=75, the JVM automatically adjusts. In a 1 GB container it takes 750 MB; in a 2 GB container it takes 1.5 GB.

A typical Dockerfile or Kubernetes container spec might look like this:

FROM eclipse-temurin:21-jre-alpine

WORKDIR /app
COPY target/myapp.jar .

ENV JAVA_OPTS="-XX:MaxRAMPercentage=75 -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

ENTRYPOINT ["java", "-jar", "$JAVA_OPTS", "myapp.jar"]

The 75% figure is a solid default. We're not aggressive because the JVM needs memory for more than just the heap. Your choice here depends on your workload: microservices with predictable memory patterns can go 80%, while applications with significant off-heap allocations should stay at 70% or below.

You can also use -XX:InitialRAMPercentage if you want fine-grained control over initial heap sizing, useful when you're optimizing for startup time versus steady-state performance.

Leave room for metaspace and threads

The heap is only part of the JVM's memory footprint. When you allocate 75% of container memory to the heap, you're leaving 25% for everything else, but you need to be intentional about what fits in that space.

Metaspace holds class metadata and bytecode. In Java 8+ this is not part of the heap (unlike PermGen in earlier versions), so it draws from off-heap memory. Spring applications, especially those using reflection-heavy libraries like Spring Data or Jackson, can accumulate significant metaspace usage. By default, metaspace is unbounded, which means it'll consume available memory until the JVM crashes.

Set an explicit metaspace limit:

-XX:MetaspaceSize=64m -XX:MaxMetaspaceSize=256m

Thread stacks are another often-forgotten allocation. Each thread reserves stack memory (typically 1 MB on 64-bit Linux). A Tomcat server with 200 threads burns 200 MB just on stacks, independent of heap size. This is off-heap memory that must come out of your container's 25% buffer.

In a memory-constrained environment, you might reduce thread stack size:

-Xss512k

Be cautious here—too small a stack causes StackOverflowError on deep recursion. Most applications work fine with 512 KB, but CPU-intensive or recursive algorithms may need the default 1 MB.

A realistic memory breakdown for a 1 GB container might be:

This breakdown shows why blindly taking 90% for heap is risky. If your Spring Boot app loads a large framework and creates many threads, you'll hit OOMKilled before you see a heap OutOfMemoryError.

Watch for OOMKilled vs OutOfMemoryError

These two failure modes look similar but come from different layers, and they require different fixes.

OutOfMemoryError: Java heap space means the JVM's garbage collector tried to allocate an object but couldn't find space in the heap. The JVM is still running and can potentially recover (if you have handlers) or you see a stack trace in logs. Example:

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
    at java.util.Arrays.copyOf(Arrays.java:3210)
    at java.util.ArrayList.grow(ArrayList.java:265)

OOMKilled (or SIGKILL 137 exit code in containers) happens when the Linux kernel terminates your entire container because total process memory (heap + off-heap + native) exceeded the cgroup limit. The JVM gets no chance to recover—the container dies instantly. You'll see nothing in Java logs; instead, look at container orchestration logs or dmesg.

Kubernetes marks this as a OutOfMemory eviction, but it's not a Java exception. Docker users see exit code 137. This is the more dangerous failure mode because there's no logging, just silence followed by a restart loop.

To diagnose which is happening:

1. Check Java application logs for stack traces—if present, it's a heap OutOfMemoryError
2. Check container exit codes: 137 means OOMKilled by the kernel
3. In Kubernetes, run kubectl describe pod and look for "OOMKilled" or "LastState.Reason"
4. Use memory monitoring during load testing: if RSS (resident set size) approaches your container limit, you have off-heap pressure

If you're getting OOMKilled, you have three options: increase container memory limit, reduce heap percentage (e.g., from 75% to 70%), or profile your application to find memory leaks in off-heap allocations like NIO buffers or caches.

Common mistakes

Mistake 1: Setting both -Xmx and -XX:MaxRAMPercentage

When both flags are present, the JVM uses the smaller value. This leads to confusion: you set -XX:MaxRAMPercentage=75 -Xmx512m expecting 75% dynamic sizing, but the JVM caps itself at 512 MB. Choose one approach: either hardcode with -Xmx (fine for fixed deployments) or use percentage flags (better for containers). Most teams should standardize on percentage flags for consistency across environments.

Mistake 2: Forgetting about IDE defaults

When testing locally, your IDE runs the JVM with its own defaults, typically generous heap settings. Your 512 MB container limit might be 10× tighter than your laptop, so an application that works fine during development fails in production. Always test containerized applications by actually running them in a container with the intended resource limits, ideally via Docker or a local Kubernetes cluster.

Mistake 3: Not accounting for GC overhead

When heap is tight, garbage collection becomes more frequent and aggressive. The JVM spends more CPU time collecting and less time running your business logic. A container with 256 MB total memory, 75% heap (192 MB), often experiences so much GC that throughput collapses. Monitor GC logs in production; if full GC cycles happen every few seconds, your heap is too small relative to your workload.

Mistake 4: Ignoring cgroup v2

Newer container systems use cgroup v2, which changes the memory limit file location and format. Java 15+ handles this correctly, but if you're stuck on Java 11, ensure your JVM version includes cgroup v2 support patches. Check your Java vendor's release notes.

Key takeaways

• Modern JVMs (Java 10+) automatically detect container memory limits via cgroups—verify this at startup by checking MaxHeapSize in verbose output.
• Replace static -Xmx flags with -XX:MaxRAMPercentage=75 to scale memory usage with container limits dynamically.
• Reserve at least 20-25% of container memory for metaspace, thread stacks, and off-heap allocations; cap metaspace explicitly with -XX:MaxMetaspaceSize.
• Distinguish between OutOfMemoryError (Java logging, recoverable) and OOMKilled (exit code 137, silent failure); both require different investigation and fixes.
• Load test containerized applications with actual resource limits applied; local testing without container constraints masks memory configuration issues.
• Monitor garbage collection behavior in production; excessive GC frequency indicates heap pressure and suggests either increasing memory or optimizing object allocation patterns.