Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Jib build fails with 401 Unauthorized against the registry

Error401 Unauthorized

Short answer

A 401 from Jib is almost always a credentials problem: Jib did not find your login, found one for another registry, or sent none over plain HTTP. Read the credential line in the Jib log, then fix the Docker config, the credential helper on PATH, or the registry name and port in the image reference.

  • Applies to Jib 3.4, Maven 3.9, Docker 28, JDK 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the build with more output and read which credentials Jib reports using for each registry. It logs the source it picked.

    mvn compile jib:build 2>&1 | grep -i -E "credential|auth|401"
  2. 2Match what you see, then jump to its fix

    1. 1No 'Using credentials from' line for the target registry in the logJib cannot find credentials for that registryFix
    2. 2docker push works in your terminal but Jib fails when it runs inside an IDE or CI stepThe credential helper is not on the PATH Jib seesFix
    3. 3Pulling the base image works and pushing fails, or the opposite; or a typo in registry host, port or image nameCredentials are right for the base image but not the target (or the other way round)Fix
    4. 4A local or internal registry reached over http://The registry is plain HTTP, so Jib does not send credentialsFix

What does the error look like?

  • 401 Unauthorized
  • Using credentials from Docker config (/home/user/.docker/config.json) for registry.example.com/app

Cause 1 of 4

Jib cannot find credentials for that registry

1Check

Jib reads the file written by docker login or podman login, in several locations. Check that the registry host is in it.

docker login registry.example.com
cat ~/.docker/config.json

2Fix

Log in to the exact registry host in the image name, or put a credential helper in config.json, or set credentials for the target in the pom. A credential helper is the documented recommendation.

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  <configuration>
    <to>
      <image>registry.example.com/team/app</image>
      <credHelper>ecr-login</credHelper>
    </to>
  </configuration>
</plugin>

3Verify

The log shows a 'Using credential helper' or 'Using credentials from' line for the target, and the push succeeds.

mvn compile jib:build

Confirmed by github.com

Did this fix it?

Cause 2 of 4

The credential helper is not on the PATH Jib sees

1Check

The IDE or CI process may start with a different PATH, so docker-credential-* helpers named in config.json are not found.

grep -n credsStore -A1 ~/.docker/config.json
which docker-credential-desktop

2Fix

Make the helper available on the PATH of the process that runs the build, or run the build from a terminal where docker login works.

PATH="$PATH:/path/to/helper/dir" mvn compile jib:build

3Verify

Jib now logs the credential helper it used.

mvn compile jib:build 2>&1 | grep -i credential

Confirmed by github.com

Did this fix it?

Cause 3 of 4

Credentials are right for the base image but not the target (or the other way round)

1Check

Jib needs a login for each registry it talks to. Check the from and to image strings for the host and the port.

grep -n -E "<image>|<from>|<to>" pom.xml

2Fix

Make sure the registry named in each image reference has its own credentials, and correct the host or port in the reference.

<configuration>
  <from><image>eclipse-temurin:21-jre</image></from>
  <to><image>registry.example.com:5000/team/app</image></to>
</configuration>

3Verify

Jib reports credentials for both registries in the log.

mvn compile jib:build 2>&1 | grep -i -E "credentials|credential helper"

Confirmed by github.com

Did this fix it?

Cause 4 of 4

The registry is plain HTTP, so Jib does not send credentials

1Check

Jib does not send authentication details over non-HTTPS connections.

curl -sI http://registry.example.com:5000/v2/

2Fix

Serve the registry over HTTPS. The FAQ names a sendCredentialsOverHttp system property for the exceptions, but does not recommend it.

mvn compile jib:build -DsendCredentialsOverHttp=true

3Verify

The push passes authentication.

mvn compile jib:build

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Use a credential helper instead of a password in the pom.
  • Keep image names with the full registry host and port in one property.
  • Run the build once after changing registries, and read the credentials lines.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.