Skip to content
javahacks.dev
DevOps

Fix Kubernetes Java Pod CrashLoopBackOff on Startup

Find why a Java pod restarts in a loop by reading previous logs, exit codes and probe events, then fix OOM kills, bad config and probes that fire too early.

8 min read
Summarize in AI
Flat illustration of a log with a failing line and a wrench, with the Kubernetes, OpenJDK, Docker, Gradle and Spring logos.

kubectl get pods shows the status that every Kubernetes user dreads:

Text
NAME                    READY   STATUS             RESTARTS      AGE
shop-7d9c8b5f6d-x2k4q   0/1     CrashLoopBackOff   6 (45s ago)   8m

CrashLoopBackOff is not an error. It is Kubernetes telling you that the container keeps stopping, and that it is waiting longer between restarts (10 seconds, then 20, 40, up to five minutes) to avoid hammering the node. The cause is always in why the container stopped, and for a Java application the reasons fall into four groups: the operating system killed the process for memory, the application exited on its own, a health probe killed it, or it was too slow to start because of CPU limits. The fastest way to decide which is to read two fields Kubernetes already recorded. This post shows how, then goes through each group with its fix, a table for quick triage and a way to debug a pod that will not stay up. Examples use Kubernetes 1.32, Spring Boot 4 and JDK 25.

Group 1: the process was killed for memory

Ask Kubernetes how the last container instance ended:

Shell
kubectl describe pod shop-7d9c8b5f6d-x2k4q | grep -A 8 'Last State'
Text
    Last State:     Terminated
      Reason:       OOMKilled
      Exit Code:    137
      Started:      Thu, 06 Nov 2026 09:20:11 +0000
      Finished:     Thu, 06 Nov 2026 09:20:41 +0000

OOMKilled with exit code 137 (128 plus signal 9) means the kernel killed the container for exceeding its memory limit. This is not a Java OutOfMemoryError: the JVM never got to throw anything. The usual cause is a heap that, with everything else the JVM uses, does not fit in the limit. Check what the limit is and what the JVM was told:

Shell
kubectl get pod shop-7d9c8b5f6d-x2k4q -o jsonpath='{.spec.containers[0].resources}'
kubectl logs shop-7d9c8b5f6d-x2k4q --previous | head -3
Text
{"limits":{"memory":"512Mi"},"requests":{"memory":"256Mi"}}
Picked up JAVA_TOOL_OPTIONS: -Xmx512m

A 512 MiB heap in a 512 MiB container has no room for metaspace, thread stacks and the code cache, so the process is killed as soon as it grows. Size the heap from the limit, not from a fixed number: -XX:MaxRAMPercentage=70 as in MaxRAMPercentage and container awareness. The budget of non-heap areas is in JVM memory areas, and the whole diagnosis with evidence is in a Java container killed by OOMKilled. If instead the JVM never starts and prints Could not reserve enough space, the heap request exceeds the limit at launch.

Group 2: the application exited on its own

When the reason is Error and the exit code is 1 (or another small number), the application ran and decided to stop, usually because startup failed:

Shell
kubectl describe pod shop-7d9c8b5f6d-x2k4q | grep -A 5 'Last State'
Text
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1

The cause is in the logs of the previous instance, since the current one may not have printed anything yet. Always use --previous:

Shell
kubectl logs shop-7d9c8b5f6d-x2k4q --previous | grep -B2 -A12 'APPLICATION FAILED TO START'
Text
***************************
APPLICATION FAILED TO START
***************************

Description:

Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.

Read the description and the action beneath it. The frequent ones in a cluster, and where each is explained:

  • A missing property or secret: Could not resolve placeholder 'DB_PASSWORD', because the environment variable or Secret was not mounted; see Could not resolve placeholder.
  • The database is unreachable at startup: Connection refused on 5432, because the database is not ready or the host name is wrong; see PSQLException connection refused.
  • The wrong Java version for the jar: UnsupportedClassVersionError, because the image's JRE is older than the build.
  • A file the process cannot write: an AccessDeniedException when the container runs as a non-root user with a read-only filesystem.
  • The command itself: a bad ENTRYPOINT or args makes the container exit in milliseconds with exec format error (wrong architecture) or no such file or directory; see a Spring Boot Docker image that does not start.

If the logs are empty and the exit code is 0 or 1 within a second, the process did not start the application at all. Check the image locally with docker run --rm <image> and compare the command in the pod spec (kubectl get pod -o yaml) with the one in the Dockerfile; a Helm value or an override of command is a common culprit. The general method for reading startup failures is in Spring Boot from first project to production.

An exit code of 0 that still loops means the process finished normally and Kubernetes restarts it because the restart policy says to. That is a job running as a Deployment, or an application that exits when its main thread ends. A web application keeps running because Tomcat's threads are non-daemon; a custom main that returns after starting a daemon thread exits.

Group 3: a probe killed it

A container that starts fine and is then restarted at a steady interval, with exit code 143 (128 plus signal 15, SIGTERM), was terminated by the kubelet. The describe output gives the reason in the events:

Shell
kubectl describe pod shop-7d9c8b5f6d-x2k4q | tail -8
Text
  Warning  Unhealthy  42s (x9 over 2m)  kubelet  Liveness probe failed: Get "http://10.4.2.17:8080/actuator/health/liveness": context deadline exceeded
  Normal   Killing    42s               kubelet  Container shop failed liveness probe, will be restarted

The liveness probe asked "are you alive" and got no answer in time, so the kubelet restarted the container. A Java application is slow to become responsive: class loading, Spring context startup and the first request take seconds, and a liveness probe that starts too early kills a healthy process before it finishes starting. Give startup its own probe, which holds off the other two until it succeeds:

deployment.yamlYAML
startupProbe:
  httpGet: { path: /actuator/health/liveness, port: 8080 }
  periodSeconds: 5
  failureThreshold: 36        # allows 36 x 5 = 180 s to start
livenessProbe:
  httpGet: { path: /actuator/health/liveness, port: 8080 }
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 3
readinessProbe:
  httpGet: { path: /actuator/health/readiness, port: 8080 }
  periodSeconds: 5

The startup probe allows up to three minutes for first success, after which liveness takes over with its normal tolerance. Choose failureThreshold x periodSeconds from your measured worst-case startup, with margin. Keep liveness cheap and independent of downstream services: if it checks the database and the database is down, every pod restarts at once, which makes the outage worse. Spring Boot's separate liveness and readiness health groups exist for this. Details on all three probes are in the Kubernetes probe documentation and the pod lifecycle reference.

Group 4: it is slow because of CPU limits

A CPU limit throttles a container by pausing it when it uses its quota in a period. Startup is CPU-heavy: the JVM compiles code and Spring scans classes, and a container with a limit of 250m (a quarter of a core) can take a minute or more to start something that takes four seconds on a laptop. The pod does not crash for CPU directly; it is slow enough that a probe or a timeout fails, so it looks like group 3. Check for throttling:

Shell
kubectl top pod shop-7d9c8b5f6d-x2k4q
kubectl exec shop-7d9c8b5f6d-x2k4q -- cat /sys/fs/cgroup/cpu.stat | grep throttled
Text
nr_throttled 412
throttled_usec 38211904

A high and rising nr_throttled during startup confirms it. The remedies are to raise the CPU limit (or drop it and keep a request), to give startup more time with the startup probe, or to reduce startup work. The JVM also sizes its internal thread pools from the visible CPUs, so a very small limit produces a serial collector and a single compiler thread, which slows warm-up further. Starting the application with fewer than 1000m is a trade you should make knowingly.

A quick table

What kubectl describe showsMeaningLook at
Reason: OOMKilled, exit 137Memory limit exceededHeap size versus limit
Reason: Error, exit 1Application failed to startkubectl logs --previous
Exit 143 with Liveness probe failed eventsProbe killed itStartup probe, probe timeouts
Exit 0, restarts foreverProcess finishedThe command and the main thread
Exit 126 or 127Command not found or not executableENTRYPOINT, permissions, architecture
Events: ImagePullBackOffImage could not be pulledRegistry credentials, tag
No restarts but PendingNot scheduledResource requests, node capacity

Debug it live

When the pod crashes too fast to inspect, change what runs and look around. Start the same image with a sleeping command and open a shell in the real environment:

Shell
kubectl debug shop-7d9c8b5f6d-x2k4q -it --copy-to=shop-debug --container=shop -- sh

Inside, run the application command by hand and watch it fail with the same environment, mounts and service account:

Shell
env | sort | grep -E 'SPRING|DB_|JAVA'
ls -l /etc/secrets /app
java -jar /app/app.jar

Compare the environment with what the code expects, check that mounted files exist with the permissions the user can read, and run the command to see the exact error. Delete the debug pod when you are done: kubectl delete pod shop-debug. If an image has no shell (a distroless image), an ephemeral debug container with a toolbox image can attach to the pod's process namespace instead. Keep one question in mind throughout: was the container killed (OOM, probe) or did it stop (exit code, logs)?

Where this does not apply

If the status is Error or ImagePullBackOff with no restarts, you do not have a crash loop. If the pod restarts only rarely, every few days, look for a slow memory leak or a node event, not startup. And if the pod is healthy but the Service returns errors, the container is fine and the problem is routing or readiness.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.