Jenkins docker.withRegistry Auth Failed - Fix Registry Login

The docker.withRegistry(...) step could not authenticate to the registry, so a push or pull was denied. The credential is missing/wrong, lacks permission to the repository, or the registry URL does not match the image name.

What this error means

A pipeline fails inside docker.withRegistry with unauthorized: authentication required, denied: requested access to the resource is denied, or Could not find credentials. The image build may have succeeded, but the push/pull was rejected.

denied: requested access to the resource is denied
# or
unauthorized: authentication required
# or, missing binding:
ERROR: Could not find credentials matching registry-creds

Common causes

Missing or wrong registry credential

The credentialsId passed to docker.withRegistry does not exist, or holds an expired/incorrect username/password (or token), so login fails.

Credential lacks push/pull permission

The account can authenticate but is not authorized to push/pull the target repository (wrong namespace, read-only token), yielding denied.

Registry URL/image name mismatch

The registry URL in withRegistry does not match the image tag’s registry prefix, so the credential is applied to the wrong host.

How to fix it

Authenticate with the right registry and credential

Pass the registry URL and a valid credentialsId, and tag the image for that registry.

docker.withRegistry('https://registry.example.com', 'registry-creds') {
  def img = docker.build("registry.example.com/team/myapp:${env.BUILD_NUMBER}")
  img.push()
  img.push('latest')
}

Fix permissions and URL match

1. Confirm the credential (Manage Jenkins → Credentials) has a current token/password with push access to the target repository.
2. Match the withRegistry URL to the image tag’s registry prefix exactly.
3. For ECR/GCR/cloud registries, use the provider’s credential helper or a short-lived token rather than a static password.

How to prevent it

• Store registry credentials with push access and reference them by stable ID.
• Tag images with the registry prefix that matches withRegistry.
• Use short-lived/credential-helper tokens for cloud registries.

Related guides