Skip to content
javahacks.dev
DevOps

Fix a Spring Boot Docker Image That Will Not Start

Fix a Spring Boot container that exits at once by reading its logs and checking the Java version, jar path, architecture, configuration and memory limit.

8 min read
Summarize in AI
Flat illustration of shipping containers stacked on a ship, with the Docker, Kubernetes and Terraform logos.

The image builds, docker run returns to the prompt a second later, and the container is gone. Or it stays up and never answers on its port. A Spring Boot image that will not start fails in a handful of ways, and each prints a distinctive line if you know where to look. The first move is always the same: read what the container said before it died. Then match the message to one of eight causes: a Java version that is too old for the jar, a jar that is not where ENTRYPOINT expects it, a jar with no main class, a CPU architecture mismatch, configuration that exists on your laptop and not in the container, a port conflict, a memory limit and file permissions. This post walks through them with the exact messages and fixes, then shows how to get a shell inside the image to look around. Examples use Docker 27, Spring Boot 4 and JDK 25.

Start with the logs of the failed container, which Docker keeps until you remove it:

Shell
docker run --name shop shop:1.0.0
docker logs shop
docker inspect shop --format '{{.State.ExitCode}} {{.State.OOMKilled}}'
Text
1 false

The exit code is the first clue (1 the application or JVM failed, 137 killed, 126 or 127 command problem, 0 finished normally) and the OOMKilled flag settles whether memory was the cause. The [docker logs reference](https://docs.docker.com/reference/cli/docker/container/logs/) covers the options. Then read the first error in the log, not the last.

Cause 1: the Java version is too old

The jar was compiled for a newer Java than the image provides:

Text
Error: LinkageError occurred while loading main class dev.javahacks.shop.ShopApplication
	java.lang.UnsupportedClassVersionError: dev/javahacks/shop/ShopApplication has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 61.0

Class file version 69 is Java 25, and 61 is Java 17. Match the runtime image to the build: if the build uses JDK 25, the image must be eclipse-temurin:25-jre, not 17. Check what the image actually contains rather than the tag you meant:

Shell
docker run --rm shop:1.0.0 java -version

The conversion table of class file versions and the full fix are in UnsupportedClassVersionError. A multi-stage Dockerfile whose build and run stages use different JDKs is the usual source.

Cause 2: the jar is not where ENTRYPOINT says

Text
Error: Unable to access jarfile /app/app.jar

The ENTRYPOINT points at a path that does not exist in the image. Typical mistakes: the jar name includes a version (shop-1.0.0.jar) while the COPY or ENTRYPOINT uses app.jar; a wildcard that matches two files; the COPY source path is relative to the build context and the file is outside it or excluded by .dockerignore; a multi-stage build copies from the wrong stage. List the image's files:

Shell
docker run --rm --entrypoint sh shop:1.0.0 -c 'ls -l /app'
Text
total 62144
-rw-r--r-- 1 root root 63631360 Nov  6 09:30 shop-1.0.0.jar

The file is shop-1.0.0.jar; the entrypoint wanted app.jar. Fix the name in one place, ideally by setting finalName in the build or copying with an explicit target name (COPY --from=build /src/target/shop-*.jar /app/app.jar, with a single match). Ensure .dockerignore does not exclude target/, if the Dockerfile copies a prebuilt jar. The Dockerfile patterns that avoid this are in writing a Java Dockerfile the right way.

Cause 3: no main manifest attribute

Text
no main manifest attribute, in /app/app.jar

The jar is not an executable Spring Boot jar. It is the plain library jar, which Maven produces before the Boot plugin repackages it, or the Boot plugin is missing from the build. Check the manifest:

Shell
unzip -p target/shop-1.0.0.jar META-INF/MANIFEST.MF | grep -E 'Main-Class|Start-Class'
Text
Main-Class: org.springframework.boot.loader.launch.JarLauncher
Start-Class: dev.javahacks.shop.ShopApplication

A Boot executable jar has Main-Class: ...JarLauncher and a Start-Class. If both are absent, add the Spring Boot Maven plugin with the repackage goal (it is part of the parent POM's lifecycle when you use spring-boot-starter-parent), and copy the repackaged jar, not *.jar.original:

pom.xmlXML
<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>

A related message, Unable to find a suitable main class, is raised at build time and is covered in fixing unable to find suitable main class. Another option that avoids the Dockerfile entirely is building the image with the plugin: mvn spring-boot:build-image, described in the container images reference.

Cause 4: architecture mismatch

Text
exec /opt/java/openjdk/bin/java: exec format error

or the warning The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8). The image was built for a different CPU architecture than the machine runs: an image built on an Apple Silicon laptop (arm64) pushed to an amd64 cluster, or the reverse. Check:

Shell
docker image inspect shop:1.0.0 --format '{{.Os}}/{{.Architecture}}'
Text
linux/arm64

Build for the target platform, or for both with a manifest list:

Shell
docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.test/shop:1.0.0 --push .

Pipelines that build on amd64 CI runners and are used on arm64 laptops need the multi-platform form. The CI recipe is in building and pushing Docker images in CI.

Cause 5: configuration inside the container

The application starts, then stops with a Spring failure report, because something the laptop provided is missing in the container: an environment variable, a profile, a file, a database that localhost no longer reaches.

Text
***************************
APPLICATION FAILED TO START
***************************

Description:

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

Inside a container, localhost is the container itself. A database URL pointing at localhost:5432 finds nothing. Pass configuration through environment variables (-e SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/shop), use a Compose network so service names resolve, and make sure required secrets are supplied. Read the report with the method in fixing Spring Boot application failed to start; the datasource case specifically is in Failed to configure a DataSource. Print the environment the container sees: docker run --rm shop:1.0.0 env | sort.

Cause 6: the port

Two port problems, in opposite directions. The application cannot bind:

Text
Web server failed to start. Port 8080 was already in use.

Inside a fresh container that means something else in the same container uses 8080 (a second process, an agent), or --network host shares the host's ports. See port 8080 already in use. More common: the application is running and unreachable, because the port is not published. EXPOSE 8080 in the Dockerfile is documentation only. You must map it when you run:

Shell
docker run -d --name shop -p 8080:8080 shop:1.0.0
curl -s localhost:8080/actuator/health
Text
{"status":"UP"}

Make sure the application listens on all interfaces. A server bound to 127.0.0.1 inside the container is unreachable from outside it; Spring Boot binds to all by default, but server.address=127.0.0.1 from a copied configuration changes that.

Cause 7: memory

Shell
docker inspect shop --format '{{.State.ExitCode}} {{.State.OOMKilled}}'
Text
137 true

Exit code 137 with OOMKilled: true means the kernel killed the container for exceeding its memory limit, with no Java stack trace. Either the limit is too low for the application (a Spring Boot application with several starters needs roughly 300 to 500 MiB at least), or the heap is sized larger than the limit. With no limit set the JVM sizes itself from the host's memory. Set the limit and let the JVM follow it:

Shell
docker run --memory=768m -e JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=70" shop:1.0.0

If the JVM fails before running at all with Could not reserve enough space for object heap, the requested heap exceeds what is available, per that error explained. The full diagnosis of a killed container is in a Java container killed by the OOM killer.

Cause 8: permissions and the user

An image that runs as a non-root user fails where the application writes: a temp directory, a log file, an upload folder.

Text
java.nio.file.AccessDeniedException: /app/logs/app.log

or Permission denied on the jar itself if the copy left it unreadable. Check who the process runs as and who owns the files:

Shell
docker run --rm --entrypoint sh shop:1.0.0 -c 'id; ls -ld /app /app/logs /tmp'
Text
uid=10001(app) gid=10001(app)
drwxr-xr-x 1 root root 4096 Nov  6 09:30 /app
drwxr-xr-x 2 root root 4096 Nov  6 09:30 /app/logs

The user app cannot write to /app/logs, owned by root. Create writable directories with the right owner in the Dockerfile, or log to stdout instead of a file. Running as non-root is correct; the fix is to own what the process writes, as set out in the non-root user post of this series. A read-only root filesystem needs a mounted writable /tmp.

Run a shell to look around

When the cause is not clear, replace the entrypoint with a shell and examine the image as the application would see it:

Shell
docker run --rm -it --entrypoint sh shop:1.0.0

Inside, run the same command by hand and watch it fail:

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

For a distroless image with no shell, use an image with a shell on the same base for debugging, or docker cp the files out and inspect them. Fix one thing at a time and rebuild; a Dockerfile fix means a new image, and layer caching makes that fast.

Where this does not apply

If the container runs but the application is unhealthy, you are past starting; read the application log. If the container works under plain Docker and fails in Kubernetes, compare the pod spec (probes, resources, security context, injected environment) with your docker run flags, starting with the crash-loop checklist in diagnosing a Java pod in CrashLoopBackOff. And if the build itself fails, the problem is earlier than the image.

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.