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.

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:
docker run --name shop shop:1.0.0
docker logs shop
docker inspect shop --format '{{.State.ExitCode}} {{.State.OOMKilled}}'1 falseThe 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:
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.0Class 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:
docker run --rm shop:1.0.0 java -versionThe 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
Error: Unable to access jarfile /app/app.jarThe 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:
docker run --rm --entrypoint sh shop:1.0.0 -c 'ls -l /app'total 62144
-rw-r--r-- 1 root root 63631360 Nov 6 09:30 shop-1.0.0.jarThe 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
no main manifest attribute, in /app/app.jarThe 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:
unzip -p target/shop-1.0.0.jar META-INF/MANIFEST.MF | grep -E 'Main-Class|Start-Class'Main-Class: org.springframework.boot.loader.launch.JarLauncher
Start-Class: dev.javahacks.shop.ShopApplicationA 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:
<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
exec /opt/java/openjdk/bin/java: exec format erroror 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:
docker image inspect shop:1.0.0 --format '{{.Os}}/{{.Architecture}}'linux/arm64Build for the target platform, or for both with a manifest list:
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.
***************************
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:
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:
docker run -d --name shop -p 8080:8080 shop:1.0.0
curl -s localhost:8080/actuator/health{"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
docker inspect shop --format '{{.State.ExitCode}} {{.State.OOMKilled}}'137 trueExit 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:
docker run --memory=768m -e JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=70" shop:1.0.0If 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.
java.nio.file.AccessDeniedException: /app/logs/app.logor Permission denied on the jar itself if the copy left it unreadable. Check who the process runs as and who owns the files:
docker run --rm --entrypoint sh shop:1.0.0 -c 'id; ls -ld /app /app/logs /tmp'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/logsThe 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:
docker run --rm -it --entrypoint sh shop:1.0.0Inside, run the same command by hand and watch it fail:
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.


