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

By Kaveh Alemi·Latchkey

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.

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

Diagnose it: which rule matched, and on which runner?

GitLab evaluates rules: top to bottom and the first match wins, including one that sets when: never. A job that does not run, or runs when you did not expect it to, is nearly always matching an earlier rule than the one you are reading.

# validate the definition against the project
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/ci/lint" \
  --data-urlencode "content=$(cat .gitlab-ci.yml)"

# what the job actually sees
script:
  - env | grep -E "^CI_(PIPELINE_SOURCE|COMMIT_REF_NAME|RUNNER)" | sort

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.

# 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

1. Make the auths key identical to the registry portion of the image: value.
2. Verify the base64 encodes username:password with no newline (base64 -w0).
3. 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.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation