Docker Hub "unauthorized: authentication required" in CI

Docker Hub returned a 401 auth challenge and the client did not satisfy it. Unlike "denied" (you authenticated but lack access), "unauthorized: authentication required" means no valid bearer token was obtained at all, usually because login never ran or the token expired.

What this error means

A docker pull or push to docker.io fails with "unauthorized: authentication required", or "Head ... unauthorized" while fetching a private base image.

docker

error parsing HTTP 401 response body: ...
unauthorized: authentication required

Common causes

No login ran before accessing a private image

Pulling a private repo or pushing without a prior docker login sends an anonymous request, which Docker Hub answers with 401.

Stale or invalid credentials

A revoked access token, a typo in the secret, or a password that requires a token instead all fail the auth challenge.

How to fix it

Authenticate before pull or push

Generate a Docker Hub personal access token.
Log in with docker/login-action at the start of the job.
Confirm the secret name matches and the token is not revoked.

.github/workflows/ci.yml

- uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

Verify the token still works

A 401 that persists means the credential is bad, not the network. Re-issue the access token and update the secret.

Terminal

echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin

How to prevent it

Run docker login in the same job that pulls or pushes.
Use access tokens and rotate them on a schedule.
Pin secret names so a rename does not silently send empty credentials.