docker pull from a private GitLab registry says access forbidden
denied: access forbiddenShort answer
GitLab answers access forbidden when it accepts your credentials but they carry no registry permission. Give the token the read_registry scope, use a token instead of a password if two-factor is on, and check your project role. In CI, use the job token for the same project.
Fix it fast
1Find out which cause you have
Log in again with a token read from stdin, then pull. The login result separates a bad credential from a missing permission.
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin docker pull registry.example.com/group/project/image:tag2Match what you see, then jump to its fix
- 1
docker login succeeds or fails, then pull says denied: access forbiddenThe token has no registry scopeFix - 2
Login with the account password is rejected although the password is rightTwo-factor authentication is on and you used your passwordFix - 3
The job log shows access forbidden for an image path that belongs to a different projectA CI job pulls an image from another projectFix - 4
Valid token, role and scope, but still access forbidden, and the instance sits behind a reverse proxyA proxy strips the Authorization headerFix
- 1
What does the error look like?
denied: access forbiddenaccess forbidden
Cause 1 of 4
The token has no registry scope
1Check
GitLab needs read_registry to pull, and read_registry plus write_registry to push. A token made for the API or Git alone does not carry it.
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin2Fix
Create a new personal, project or group access token (or a deploy token) with read_registry, and use it as the password. For pushing, add write_registry.
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin3Verify
The pull completes.
docker pull registry.example.com/group/project/image:tagConfirmed by docs.gitlab.com
Cause 2 of 4
Two-factor authentication is on and you used your password
1Check
When two-factor authentication is enabled on the GitLab account, GitLab does not accept the password for the registry; a token is required.
echo "$PASSWORD" | docker login registry.example.com -u <username> --password-stdin2Fix
Log in with a token that has read_registry as the password.
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin3Verify
docker login prints Login Succeeded.
docker pull registry.example.com/group/project/image:tagConfirmed by docs.gitlab.com
Cause 3 of 4
A CI job pulls an image from another project
1Check
The CI job token has read and write access to the registry of the job's own project. Other projects are controlled by the job token allowlist.
grep -n 'CI_REGISTRY\|CI_JOB_TOKEN' .gitlab-ci.yml2Fix
For the job's own project log in with the job token. For another project, add your project to that project's job token allowlist, or log in with a deploy token.
echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin3Verify
Re-run the pipeline and watch the pull step pass.
docker pull $CI_REGISTRY_IMAGE:latestConfirmed by docs.gitlab.com
Cause 4 of 4
A proxy strips the Authorization header
1Check
GitLab names a proxy that removes the Authorization header on the /jwt/auth request as a cause of this error. Look for any proxy, load balancer or WAF between Docker and GitLab, and read its header rules.
docker pull registry.example.com/group/project/image:tag2Fix
Change the proxy or load balancer so it forwards the Authorization header to GitLab unchanged, then log in again.
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin3Verify
The pull works once the header reaches GitLab.
docker pull registry.example.com/group/project/image:tagConfirmed by docs.gitlab.com
How do I stop it coming back?
- Use one token per purpose, with only read_registry for machines that pull.
- Store tokens as CI variables or secrets and always pass them with --password-stdin.
- Keep a note of token expiry dates so a pull does not fail on the day a token ends.
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
Servers
docker pull says access denied or repository does not exist
Error response from daemon: pull access denied for <image>
Docker prints this when it cannot find the image under that name with your current credentials.
3 causes, each with a fixServers
docker push is denied: requested access to the resource is denied
push access denied, repository does not exist or may require authorization
The registry refused the push.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fix