The heap is only part of the process
A Java process can be terminated by its container memory limit even when its heap is below the configured maximum. Threads, code, class metadata, direct buffers and other native allocations also require memory. Setting the maximum heap equal to the container limit leaves no deliberate room for those consumers.
This guide concerns JVM applications in constrained environments. A Java OutOfMemoryError and a container-level termination are different observations. Establish which occurred before choosing a remedy. The absence of a Java heap error does not prove that memory played no part in the restart.
Setup: inventory the effective budget
Record the JDK vendor and version, container limit, JVM options, thread count and workload concurrency. Capture effective runtime settings rather than only a deployment manifest. The Java command reference describes container-aware memory sizing and heap percentage options; behavior must be checked for the deployed JDK.
Identify which metrics describe used heap, committed heap, total resident memory and the container's accounting. They are different quantities. Review native-memory tracking support and its operating overhead before enabling it. The official reference describes summary and detail modes for JVM subsystems, but those measurements do not imply complete accounting of every third-party native allocation.
Illustrative incident: heap looks healthy before a restart
An illustrative API increases its worker-thread count and then begins restarting under load. Heap charts remain below the maximum, so the team initially dismisses memory pressure. Container termination evidence and process measurements show a broader budget problem. This constructed example does not claim a production benchmark or customer outcome.
Correlate the restart time with container events, resident memory, thread growth, direct-buffer use and request concurrency. Keep heap dumps and diagnostic files under restricted access because they can contain application data and credentials.
Troubleshooting: classify the exhausted resource
| Observation | Evidence | Investigation |
|---|---|---|
| Container kills the process | Runtime termination reason and limit accounting | Did total process usage exceed the budget? |
| Heap error is logged | Heap profile and allocation behavior | Is the Java object workload bounded? |
| Resident memory grows while heap is stable | Threads, direct buffers and native categories | Which non-heap owner is growing? |
| Pressure follows concurrency | Per-request resources and thread policy | Is admission larger than the memory envelope? |
Do not infer a leak from one rising graph during warm-up. Compare a stable workload, completed garbage-collection cycles and resource release over time. Equally, do not assume every unexplained native increase will disappear after a heap collection.
Corrective action from measured demand
Choose a heap budget with deliberate space for non-heap demand and operational variation. Bound threads, buffers and admitted work where the evidence identifies those consumers. Increasing the container limit may be appropriate, but it should follow a capacity decision rather than replace investigation.
Change one relevant dimension at a time in staging. Keep the previous runtime configuration and application release available for rollback. Avoid copying a heap percentage from a tutorial as a universal production setting; workload shape, JDK implementation and sidecars or platform accounting can change the safe envelope.
Verification, capacity SLO and SOP
Exercise realistic concurrency, large payloads, dependency delays and shutdown. Observe total process memory as well as heap and verify that completed work releases expected resources. Confirm that the service remains useful within the accepted workload envelope, not merely that a restart happens later.
An internal SLO should concern successful requests or jobs at the agreed capacity. Memory headroom is a supporting guardrail, and a customer SLA requires separate terms. The SOP should document diagnostic access, termination classification, approved runtime options, workload limits and escalation evidence. Do not promise that native-memory tracking alone will identify every memory consumer.
See software development and containers and Kubernetes.
Technical reference
Oracle Java command and memory options, reviewed 19 October 2026. Follow documentation matching the installed product version.