How to Fix Java Container Issues on Azure: JVM & Memory

Before touching a single JVM flag, you need to know what memory your container actually has. This sounds obvious, but I've seen teams spend hours tuning JVM parameters only to realize their container was misconfigured with 512 MB when the app needed 4 GB.

On Kubernetes (AKS), check your current resource limits:

kubectl describe pod <your-pod-name> -n <namespace>

Look for the Limits section under your container. On Azure Container Apps, open the Azure Portal, navigate to your Container App → Containers → Edit & deploy → select your container image → check CPU and Memory.

Now ask yourself: is this enough for your workload? If you're not sure, Microsoft's official guidance is to start with 4 GB of container memory. That's a good default for most Java container memory allocation decisions, especially for Spring Boot applications. If your application builds large object graphs, processes lots of data in-memory, or caches heavily, you'll need more.

A quick way to check what the JVM actually sees when it starts is to add these diagnostic flags temporarily:

-XX:+PrintFlagsFinal -XX:+PrintGCDetails -Xlog:gc*

These will dump GC configuration and memory settings at startup. Look for MaxHeapSize in the output, if it's anywhere near your container's total memory limit, you have a misconfiguration and an OOM crash is just a matter of time.

For existing applications migrating from on-premises: start with the same memory the app currently uses on its VM or bare-metal host. If the old server had 8 GB allocated to this Java process, start your container at 8 GB. Don't assume smaller is fine just because "containers are lightweight."

When the step is done correctly, you should know exactly how much container memory you have and roughly how much heap the JVM is currently trying to claim.

This is where most of the confusion lives. There are multiple ways to set JVM heap size in containers, and picking the wrong flag, or misreading what a flag actually does, will cause crashes even when your numbers look right on paper.

Here's the breakdown of the flags you'll actually use:

# Fixed maximum heap, use when you know exactly how much you want
-Xmx4g

# Dynamic maximum heap, use this in containers (preferred)
-XX:MaxRAMPercentage=75

# Set initial heap to match max (prevents heap resizing at startup)
-XX:InitialRAMPercentage=75

# Minimum heap size (use with -XX:InitialRAMPercentage for containers)
-Xms3g   # absolute value alternative

The one flag I need to specifically call out: -XX:MinRAMPercentage. Despite what the name suggests, this flag does not set the minimum heap size for your container. It sets the default maximum RAM percentage for systems with 256 MB or less of available memory. If you use this flag thinking it controls minimum heap on a normal container, you'll be confused why nothing changes. Use -XX:InitialRAMPercentage for minimum/initial heap instead.

The golden rule for JVM heap size container configuration: never set max heap equal to container memory. The JVM needs memory beyond the heap, for thread stacks, class metadata (Metaspace), JIT compilation buffers, GC internal data, and native libraries. Set the heap to 100% of container memory and you will hit container OOM errors. The container's OOM killer doesn't care about JVM internals; it just sees memory usage exceeding the limit and kills the process.

75% is the recommended allocation. On a 4 GB container that means 3 GB for heap and 1 GB breathing room for everything else. On an 8 GB container, 6 GB for heap. Use -XX:MaxRAMPercentage=75 rather than hardcoded -Xmx values whenever possible, it scales automatically if you change container size later, which saves a configuration headache down the road.

You'll know this step worked when your pod no longer shows exit code 137 (OOM kill) in the event log and JVM startup logs show a MaxHeapSize that's approximately 75% of your container limit.

Picking the wrong GC for Java applications in containers is one of the most common, and most impactful, configuration mistakes I see on Azure deployments. The JVM will pick a GC for you if you don't specify one, but its choice is based on heuristics that don't always translate well to containerized environments.

Here's a plain-English breakdown of which GC to use and when:

SerialGC, single-threaded, meant for single-core or very small-heap situations (under 4 GB). High pause times. Not great for any production workload that handles concurrent requests. You'd only choose this deliberately for a very constrained sidecar container or a batch job with no latency requirements.

ParallelGC, multi-threaded, great for heaps under 4 GB, minimal overhead. This is the recommended starting point for most Java microservices on Azure. If your app is a REST API, a Spring Boot service, or a standard microservice, start here.

G1GC, designed for heaps of 4 GB and above. More overhead than ParallelGC but better at keeping pause times predictable. If your heap needs to be 4 GB or larger, G1GC is a good choice. Needs at least 2 vCPU cores to function well.

ZGC, available from JDK 17+. Sub-millisecond pause times, designed for very large heaps. Best for latency-sensitive workloads like APIs with strict SLAs. More CPU overhead than G1GC. Needs 2+ cores.

ShenandoahGC, available from JDK 11+. Pause times under 10ms, handles medium to large heaps well. Good for request-response and database-heavy workloads where ZGC's JDK 17 requirement is a blocker.

For most teams reading this guide: start with ParallelGC. The flag is:

-XX:+UseParallelGC

If you need G1GC:

-XX:+UseG1GC

For ZGC on JDK 17+:

-XX:+UseZGC

Two cores are required for any GC besides SerialGC. On Kubernetes, make sure your cpu_limit is at least 2000m before choosing ParallelGC, G1GC, ZGC, or ShenandoahGC. Running a multi-threaded GC on less than one vCPU core is a recipe for CPU throttling and degraded throughput.

You'll know this step worked when GC pause times stabilize in your application logs and you stop seeing unexpected latency spikes correlated with GC events.

Memory gets most of the attention in Java container performance tuning, but CPU configuration is just as important, and just as frequently misconfigured. The JVM uses the number of "available processors" to make decisions about GC thread counts, JIT compiler parallelism, and even the default GC selection. Get this wrong and you'll see CPU throttling, degraded throughput, and erratic behavior.

The official recommendation is to start with 2 vCPU cores. On Kubernetes, that looks like this:

resources:
  requests:
    cpu: "2"
  limits:
    cpu: "2"

On Azure Container Apps, go to your container's resource settings and set CPU to 2.0 cores. On Azure Spring Apps, this is set at the app level under Scale and replicas.

One thing to be aware of: if your container has a CPU quota applied (common in shared AKS clusters), the JVM might still see all the node's CPUs when it counts "available processors." Newer JVM versions (OpenJDK 11+) are container-aware and will use the CPU quota to calculate available processors, but this depends on the JVM being run with container support enabled. Verify your JDK version is 11 or later and that the JVM isn't being launched with -XX:-UseContainerSupport (that flag disables container awareness and causes the JVM to see host CPUs instead of the container quota).

To check container support status at startup, add this diagnostic flag temporarily:

-XX:+PrintFlagsFinal | grep UseContainerSupport

It should show true. If it doesn't, remove any flag that disables it.

For replicas: Microsoft recommends starting with 2 replicas in any container orchestration environment, AKS, OpenShift, Azure Spring Apps, Azure Container Apps, or Azure App Service. A single replica is a single point of failure. Two gives you redundancy and lets you roll updates without downtime. The full recommended starting configuration is: 2 vCPU cores, 4 GB container memory, 75% heap, ParallelGC, 2 replicas.

After setting this, watch your pod CPU metrics in Azure Monitor for a few minutes of load. If you see CPU consistently throttled (Kubernetes will report this as cpu_throttled_seconds_total in Prometheus metrics), increase your CPU limit before increasing replica count.

Configuration is half the battle. The other half is knowing whether your changes actually made a difference, and whether the resources you've allocated are too much, too little, or just right. An over-provisioned container wastes money. An under-provisioned one degrades performance. Finding the right balance requires a baseline.

Azure Application Insights is the recommended tool for establishing a baseline for containerized Java applications. It gives you visibility into heap usage over time, GC activity, CPU consumption, and request latency, all the signals you need to tune your configuration with data instead of guesswork.

To set up Application Insights for a Java container, use the OpenTelemetry-based auto-instrumentation agent. Download the agent JAR from the Azure portal or Maven Central and add it to your container startup:

-javaagent:/path/to/applicationinsights-agent.jar

Set the connection string as an environment variable in your container:

env:
  - name: APPLICATIONINSIGHTS_CONNECTION_STRING
    value: "InstrumentationKey=your-key-here;IngestionEndpoint=https://..."

Once connected, navigate to Azure Portal → Application Insights → Performance to see request latency and throughput. For JVM-specific metrics, go to Metrics → Add metric and look for metrics under the azure.applicationinsights namespace, you'll find JVM heap used, GC count, GC time, and more.

What you're looking for in the baseline: does heap usage grow unboundedly over time (memory leak) or does it stabilize? Are GC pause times consistent or are there occasional long pauses that correlate with latency spikes? Is CPU usage near the limit (suggesting you need more cores) or near zero (suggesting you're over-provisioned)?

Run your application under realistic load, not just idle, for at least 15–30 minutes before drawing conclusions. JVM JIT compilation and class loading front-load CPU usage at startup, so early metrics won't represent steady-state behavior. Once you have steady-state data, you have a real baseline to compare against when you make future configuration changes.

You'll know this step is working when you can see live heap, CPU, and GC metrics in the Application Insights dashboard and your container is no longer restarting unexpectedly.