Docker를 사용하다 보면 한 번쯤은 마주치게 되는 골치 아픈 에러가 있습니다. 바로 pull access denied for image, repository does not exist or may require 'docker login' 에러인데요. 이번 글에서는 이 에러의 원인과 확실한 해결방법을 차근차근 알아보겠습니다.
1. 에러가 발생하는 주요 원인들
Docker pull access denied 에러는 여러 가지 이유로 발생할 수 있습니다. 이 에러는 일반적으로 접근 권한이 없는 이미지를 pull하려고 할 때 발생하는데, 구체적인 원인들을 살펴보겠습니다.
잘못된 이미지 이름 입력
가장 흔한 원인 중 하나는 단순한 오타입니다. 예를 들어:
docker pull ngnix # 올바른 이름: nginx
docker pull mysql:8.0.30 # 존재하지 않는 태그
존재하지 않는 리포지터리
때로는 이미지 자체가 존재하지 않는 경우가 있습니다. Docker Hub에서 이미지가 삭제되었거나, 처음부터 존재하지 않았을 수도 있죠.
프라이빗 리포지터리 접근
공개되지 않은 개인 또는 조직의 프라이빗 리포지터리에 접근할 때는 반드시 인증이 필요합니다.
Docker Hub 레이트 리밋
Docker Hub은 인증되지 않은 사용자에게 6시간당 pull 횟수 제한을 적용합니다. 2025년 현재 기준으로:
- 인증되지 않은 사용자: 시간당 10회 또는 6시간당 60회
- 인증된 무료 사용자: 시간당 40회 또는 6시간당 240회
2. 단계별 해결방법
Docker Hub 로그인하기
가장 기본적이면서도 효과적인 해결방법입니다.
docker login
실행하면 사용자명과 비밀번호를 입력하라는 프롬프트가 나타납니다:
Username: your-docker-username
Password: your-docker-password
로그인이 성공하면 Docker Hub 계정의 인증된 사용자 권한으로 더 많은 pull이 가능해집니다.
이미지 이름 정확성 검증
Docker Hub에서 정확한 이미지 이름을 확인해보세요:
잘못된 예시
| 잘못된 예시 | 올바른 예시 |
|---|---|
mysql:latest |
mysql:8.0 |
node:16 |
node:16-alpine |
ubuntu:20 |
ubuntu:20.04 |
네임스페이스 확인
Docker 이미지는 다음과 같은 구조를 가집니다:
[registry]/[namespace]/[repository]:[tag]
예시:
- 공식 이미지:
nginx:latest(namespace 생략) - 사용자 이미지:
username/my-app:v1.0 - 조직 이미지:
company/internal-tool:latest
3. Docker Hub 레이트 리밋 해결하기
인증을 통한 리밋 증가
인증된 사용자는 200 pull requests per 6 hours로 제한이 증가됩니다. 무료 계정이라도 로그인만으로 상당한 개선을 볼 수 있어요.
대안 레지스트리 사용
Docker Hub 외에도 여러 대안이 있습니다:
Amazon ECR Public Gallery
docker pull public.ecr.aws/nginx/nginx:latest
Google Container Registry 미러
# /etc/docker/daemon.json 파일 수정
{
"registry-mirrors": ["https://mirror.gcr.io"]
}
Microsoft Container Registry
docker pull mcr.microsoft.com/dotnet/aspnet:6.0
프록시 캐시 설정
Harbor와 같은 컨테이너 레지스트리의 프록시 캐시 기능을 사용하면 자주 사용하는 이미지가 자동으로 저장되어 Docker Hub 제한에 걸리지 않고 pull할 수 있습니다.
4. CI/CD 환경에서의 해결책
GitHub Actions에서
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
GitLab CI에서
before_script:
- echo $DOCKER_PASSWORD | docker login -u $DOCKER_USERNAME --password-stdin
Kubernetes에서
Secret을 생성하여 이미지 pull시 인증 정보를 사용:
kubectl create secret docker-registry docker-hub-secret \
--docker-server=https://index.docker.io/v1/ \
--docker-username=your-username \
--docker-password=your-password \
--docker-email=your-email
5. 그래도 해결이 안되면, 추가적인 방법으로 트러블슈팅 해보자!
Docker 데몬 로그 확인
sudo journalctl -u docker.service --since "1 hour ago"
네트워크 연결 테스트
curl -I https://registry-1.docker.io/v2/
현재 레이트 리밋 상태 확인
토큰을 가져와서 현재 레이트 리밋 상태를 확인할 수 있습니다:
TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest
멀티아키텍처 이미지 고려사항
멀티아키텍처 이미지의 경우 각기 다른 아키텍처마다 별도의 pull로 계산되므로 이를 염두에 두고 사용하세요.
Docker pull access denied 에러는 처음엔 복잡해 보이지만, 원인을 정확히 파악하고 적절한 해결방법을 적용하면 쉽게 해결할 수 있습니다. 특히 최근 Docker Hub의 레이트 리밋 정책 변화로 인해 인증의 중요성이 더욱 커졌으니, 평소에 Docker Hub 계정으로 로그인해서 사용하는 습관을 기르시면 좋겠습니다.