Sửa lỗi "pull access denied, repository does not exist or may require docker login"

Tình huống gặp lỗi

Bạn chạy docker pull — từ dòng lệnh, khi build Dockerfile, hoặc qua docker-compose up — và Docker từ chối:

$ docker pull mycompany/myapp:latest
Error response from daemon: pull access denied for mycompany/myapp,
repository does not exist or may require 'docker login':
denied: requested access to the resource is denied

Nội dung lỗi đầy đủ là:

pull access denied, repository does not exist or may require 'docker login'

Có ba nguyên nhân gây ra lỗi này: chưa xác thực, sai tên image, hoặc repository không tồn tại. Cách xử lý mỗi trường hợp sẽ khác nhau.

Nguyên nhân gây lỗi

• Chưa đăng nhập vào registry — các repo private yêu cầu xác thực trước khi Docker xác nhận sự tồn tại của chúng
• Sai tên image hoặc tag — ví dụ điển hình là gõ nginx:lastest thay vì nginx:latest
• Sai registry — image nằm trên ghcr.io hoặc registry tự host, không phải Docker Hub
• Image chưa được push hoặc đã bị xóa — repository thực sự không tồn tại
• Credentials hết hạn hoặc bị thu hồi — Personal access token của Docker Hub mặc định hết hạn sau 1 năm (hoặc ngay lập tức nếu ai đó đã xoay vòng token thủ công)

Chẩn đoán nhanh

Kiểm tra trạng thái đăng nhập hiện tại

cat ~/.docker/config.json

Xem phần key auths. Nếu là object rỗng hoặc thiếu URL registry của bạn thì bạn chưa đăng nhập — đó chính là nguyên nhân rồi.

Xác minh tên image

# Tìm kiếm image công khai trên Docker Hub
docker search postgres

# Kiểm tra các tag có sẵn qua API
curl -s "https://hub.docker.com/v2/repositories/library/node/tags/?page_size=10" | python3 -m json.tool | grep '"name"'

Đồng thời kiểm tra lại docker-compose.yml hoặc Dockerfile để xem tên image chính xác. Thiếu namespace (myapp so với myorg/myapp) hoặc gõ sai một ký tự trong tag rất dễ bỏ qua.

Cách sửa 1 — Đăng nhập vào Docker Hub

Chín trong mười trường hợp, chỉ cần làm điều này là xong:

docker login

Nhập username Docker Hub và personal access token. Docker không còn chấp nhận mật khẩu thông thường cho xác thực CLI — hãy tạo token tại hub.docker.com → Account Settings → Security → New Access Token.

Kết quả thành công sẽ hiện:

Login Succeeded

Sau đó thử pull lại:

docker pull mycompany/myapp:latest

Cách sửa 2 — Đăng nhập vào registry không phải Docker Hub

Sai registry là trường hợp dễ bị nhầm lẫn. Tên image trông có vẻ đúng, nhưng image lại nằm ở nơi khác chứ không phải Docker Hub.

GitHub Container Registry (ghcr.io)

docker login ghcr.io -u YOUR_GITHUB_USERNAME -p YOUR_GITHUB_TOKEN
docker pull ghcr.io/owner/image:tag

GitHub token cần có scope read:packages. Nếu thiếu scope này, bạn vẫn sẽ gặp lỗi access denied dù credentials hợp lệ.

AWS ECR

aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789.dkr.ecr.us-east-1.amazonaws.com

docker pull 123456789.dkr.ecr.us-east-1.amazonaws.com/myimage:latest

Registry tự host

docker login registry.mycompany.com
docker pull registry.mycompany.com/myapp:latest

Cách sửa 3 — Sửa tên image

Vẫn gặp lỗi sau khi đã đăng nhập? Tên image có thể bị sai. Đây là những lỗi phổ biến nhất:

• Thiếu namespace: myapp thay vì myorg/myapp
• Thiếu tiền tố registry: myimage thay vì registry.mycompany.com/myimage
• Sai tag: :lastest, :mian, hoặc :3.1 trong khi tag thực tế đã publish là :3.1.0

# So sánh với danh sách image hiện có local
docker images

# Pull với tên đầy đủ đã được xác minh
docker pull nginx:1.25-alpine

Giải pháp lâu dài — Lưu credentials cố định

Phải chạy docker login lại mỗi phiên làm việc rất tốn công. Credential helper lưu thông tin đăng nhập an toàn để Docker tự xử lý xác thực.

Linux

# Cài credential helper dựa trên pass
VERSION=0.8.0
wget https://github.com/docker/docker-credential-helpers/releases/download/v${VERSION}/docker-credential-pass-v${VERSION}.linux-amd64
chmod +x docker-credential-pass-v${VERSION}.linux-amd64
sudo mv docker-credential-pass-v${VERSION}.linux-amd64 /usr/local/bin/docker-credential-pass

# Cấu hình Docker sử dụng credential helper
mkdir -p ~/.docker
echo '{"credsStore": "pass"}' > ~/.docker/config.json

macOS / Windows

Docker Desktop xử lý việc này tự động — credentials được lưu vào system keychain. Chỉ cần docker login một lần và thông tin sẽ được giữ qua các lần khởi động lại.

Dành cho CI/CD pipeline

Gặp lỗi này trong GitHub Actions hoặc GitLab CI? Các runner không được cài sẵn Docker credentials. Bạn cần thêm bước đăng nhập tường minh.

# GitHub Actions
- name: Log in to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

# GitLab CI
before_script:
  - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

Hãy lưu credentials trong secret manager của nền tảng CI. Hardcode chúng vào file config là một sự cố bảo mật đang chờ xảy ra.

Kiểm tra kết quả

Sau khi đăng nhập hoặc sửa tên image:

docker pull mycompany/myapp:latest

Pull thành công sẽ hiển thị như sau:

latest: Pulling from mycompany/myapp
a8b37f1f5f40: Pull complete
Digest: sha256:abc123...
Status: Downloaded newer image for mycompany/myapp:latest

Xác nhận image đã tải về local:

docker images | grep myapp

Lưu ý thêm

• Trong môi trường production hãy dùng tag phiên bản cụ thể — myapp:1.4.2 an toàn hơn nhiều so với myapp:latest, vì latest có thể âm thầm trỏ sang image khác sau lần push tiếp theo
• Xoay vòng access token định kỳ. Token chỉ để pull thì chỉ cần quyền đọc — không có lý do gì cấp quyền ghi cho tài khoản service dùng để deploy
• Khi tạo service account cho registry tự host, hãy dùng mật khẩu ngẫu nhiên mạnh — trình tạo mật khẩu của ToolCraft thực hiện hoàn toàn phía client, không gửi dữ liệu lên server
• Với các workflow docker-compose theo nhóm, hãy thêm docker login vào script setup hoặc Makefile. Thành viên mới sẽ cảm ơn bạn vì không phải đụng vào lỗi này ngay ngày đầu tiên