GitLab CI "DOCKER_AUTH_CONFIG" Errors - Private Image Pull Auth Fails

For pulling a job’s image:/services: from a private registry, the runner authenticates using DOCKER_AUTH_CONFIG. Bad JSON, a wrong registry key, or an unmasked base64 makes the pull fail with no auth.

What this error means

The job fails during preparation pulling the image: - "no basic auth credentials" or "unauthorized" - even though DOCKER_AUTH_CONFIG is configured. An in-script docker login would not help because the failure is the runner pulling the job image, not your script.

Job log

ERROR: Job failed: failed to pull image "registry.example.com/app:1.2.3":
Error response from daemon: Get "https://registry.example.com/v2/app/manifests/1.2.3":
no basic auth credentials

Common causes

Malformed DOCKER_AUTH_CONFIG JSON

The value must be valid JSON of the form { "auths": { "registry": { "auth": "<base64>" } } }. A trailing comma, wrong quoting, or extra whitespace from a multi-line CI variable breaks parsing.

Registry key does not match the image host

The key under auths must exactly match the registry hostname (and port) in the image: reference. A mismatch (registry.example.com vs registry.example.com:443) is treated as no credentials.

Wrong base64 auth token

The auth field is base64 of username:password. An incorrectly encoded or wrapped value fails authentication.

How to fix it

Set a valid DOCKER_AUTH_CONFIG variable

Store the JSON as a CI/CD variable (masked) with the registry host as the exact key.

CI/CD variable

# value of the DOCKER_AUTH_CONFIG CI/CD variable:
{
  "auths": {
    "registry.example.com": {
      "auth": "$(printf '%s' 'user:token' | base64 -w0)"
    }
  }
}

Match the registry host exactly

Make the auths key identical to the registry portion of the image: value.
Verify the base64 encodes username:password with no newline (base64 -w0).
A transient registry 5xx/timeout during the pull clears on retry - re-run the job once credentials are confirmed correct.

How to prevent it

Store DOCKER_AUTH_CONFIG as a masked CI/CD variable, not in the YAML.
Keep the auths key matching the exact registry host used in images.
Encode the auth token with base64 -w0 to avoid stray newlines.