Maven Jib / spring-boot:build-image Failure - Fix Image Build in CI

By Kaveh Alemi·Latchkey

A container-image build with Jib or Spring Boot’s build-image failed. The usual causes are registry authentication (401/403) when pushing or pulling the base image, an unreachable base image, or - for build-image - no Docker daemon for the buildpacks builder. Pure network pulls can also blip transiently.

What this error means

The image build fails with Build to <registry>/... failed, Unauthorized/403 Forbidden against the registry, Cannot run program "docker", or a base-image pull timeout. The compile and test phases succeeded; only image creation failed.

mvn output

[ERROR] Failed to execute goal com.google.cloud.tools:jib-maven-plugin:3.4.3:build
(default-cli) on project app: Build image failed, perhaps you should make sure
your credentials for 'registry.example.com/app' are set up correctly ...
Unauthorized (401)

Diagnose it: which JDK is the build actually using?

JVM builds resolve a toolchain from several sources, and the one on PATH is often not the one compiling your code. A version mismatch surfaces as an unsupported class file version rather than as a toolchain error.

Terminal

java -version 2>&1
echo "JAVA_HOME=$JAVA_HOME"
./gradlew -q javaToolchains 2>/dev/null || mvn -v

# class file 65 = Java 21, 61 = Java 17, 55 = Java 11
javap -verbose <SomeClass>.class | grep "major version"

Common causes

Registry authentication missing or wrong

Jib pushes (and may pull a private base) using credential helpers or <to>/<from> auth. Absent or stale CI credentials yield 401/403 against the registry.

No Docker daemon for build-image, or a base-image pull failure

Spring Boot build-image runs buildpacks against a Docker daemon - none available means Cannot run program "docker". A slow or unreachable base-image registry can also time out the pull (often transient).

How to fix it

Supply registry credentials in CI

Provide auth for both the source (base image) and target registries via environment or plugin config.

.github/workflows/ci.yml

- run: mvn -B compile jib:build \
    -Djib.to.auth.username=${{ secrets.REG_USER }} \
    -Djib.to.auth.password=${{ secrets.REG_TOKEN }} \
    -Djib.from.auth.username=${{ secrets.BASE_USER }} \
    -Djib.from.auth.password=${{ secrets.BASE_TOKEN }}

For build-image, ensure a Docker daemon (or use jib:build daemonless)

build-image needs Docker; Jib’s jib:build pushes to a registry without a daemon, which is friendlier to CI.

Terminal

# build-image needs Docker available:
docker info >/dev/null   # must succeed
mvn -B spring-boot:build-image
# OR avoid the daemon entirely with Jib registry push:
mvn -B compile jib:build

How to prevent it

Inject registry credentials from CI secrets for both from and to.
Prefer jib:build (daemonless registry push) in CI over Docker-dependent build-image.
Pin and mirror base images to reduce dependence on a public registry.

Frequently asked questions

What causes Maven jib / spring-boot:build-image failure?

There are 2 common causes: registry authentication missing or wrong and no docker daemon for build-image, or a base-image pull failure. Jib pushes (and may pull a private base) using credential helpers or <to>/<from> auth.

How do I fix Maven jib / spring-boot:build-image failure?

There are 2 fixes depending on which cause you have: supply registry credentials in ci and for build-image, ensure a docker daemon (or use jib:build daemonless). Work through them in order, since the first is the most common.

What does Maven jib / spring-boot:build-image failure actually mean?

The image build fails with Build to <registry>/...

How do I stop Maven jib / spring-boot:build-image failure happening again?

Inject registry credentials from CI secrets for both from and to. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.