Vấn đềTất cả chúng ta đều đã từng gặp trường hợp này. Bạn chạy lệnh docker pull thông thường, nhưng thay vì thanh tiến trình, bạn lại nhận được lỗi 'manifest unknown'. Điều này thường xảy ra khi Docker daemon tìm thấy repository nhưng không thể xác định phiên bản cụ thể mà bạn yêu cầu. Nó gây khó chịu vì thông báo lỗi khá mơ hồ, khiến bạn tự hỏi liệu image đó có thực sự tồn tại hay không.
Error response from daemon: manifest for <image>:<tag> not found: manifest unknown: manifest unknown
Tại sao lỗi này xảy raLỗi này về cơ bản có nghĩa là có sự mất kết nối giữa yêu cầu của bạn và những gì registry đang có. Dưới đây là những nguyên nhân phổ biến nhất:
- Lỗi đánh máy: Chỉ cần một dấu gạch ngang đặt sai chỗ hoặc một chữ cái viết thường thay vì viết hoa sẽ làm hỏng yêu cầu.- Bẫy 'latest': Docker mặc định chọn
:latest nếu bạn không chỉ định tag. Tuy nhiên, nhiều quy trình CI/CD hiện đại chỉ gắn tag cho image bằng số phiên bản như v1.2.0 hoặc Git commit SHA, để trống vị trí latest.- Không tương thích kiến trúc: Bạn có thể đang dùng Mac M2 và cố gắng pull một image chỉ hỗ trợ amd64. Nếu registry không có manifest cho phần cứng cụ thể của bạn, nó có thể trả về lỗi này.- Sự cố đồng bộ Registry: Các private registry như Harbor hoặc Nexus đôi khi bị lỗi metadata hoặc quá trình push bị gián đoạn, dẫn đến các image 'ma' trông có vẻ tồn tại nhưng thiếu manifest hợp lệ.## Cách khắc phục### 1. Xác minh Tag tồn tạiĐừng bao giờ mặc định một tag tồn tại chỉ vì repository đó tồn tại. Hãy kiểm tra giao diện người dùng (UI) của registry trước. Đối với các image công khai, hãy truy cập Docker Hub và tìm kiếm image của bạn trong tab 'Tags'.
Nếu bạn thích sử dụng dòng lệnh, bạn có thể truy vấn trực tiếp API của registry. Ví dụ, để xem các tag của image Python chính thức:
curl -L -s 'https://registry.hub.docker.com/v2/repositories/library/python/tags?page_size=5' | jq '."results"[].name'
2. Lưu ý chữ hoa chữ thườngDocker tag phân biệt nghiêm ngặt chữ hoa chữ thường. Trong khi my-image:Beta và my-image:beta trông có vẻ giống nhau đối với con người, Docker daemon coi chúng là hai thực thể hoàn toàn khác biệt. Đảm bảo lệnh pull của bạn khớp chính xác với định dạng chữ trong registry.
3. Chỉ định phiên bản thay vì 'latest'Dựa dẫm vào tag mặc định là một sai lầm phổ biến. Nếu nhóm của bạn sử dụng semantic versioning (định danh phiên bản theo ngữ nghĩa), hãy thử pull một phiên bản cụ thể. Ví dụ, thay vì docker pull node, hãy thử một phiên bản ổn định cụ thể:
docker pull node:20.11-bookworm-slim
4. Ép buộc kiến trúc nền tảng (Platform)Với sự trỗi dậy của Apple Silicon (M1/M2/M3) và các máy chủ đám mây dựa trên ARM, việc không tương thích kiến trúc diễn ra rất phổ biến. Nếu bạn đang dùng Mac và image chỉ được build cho máy chủ Intel/AMD64, Docker có thể không tìm thấy manifest phù hợp. Bạn thường có thể bỏ qua lỗi này bằng cách ép buộc nền tảng:
docker pull --platform linux/amd64 mysql:8.0
5. Sử dụng Skopeo để kiểm tra chuyên sâuKhi Docker CLI không cung cấp đủ thông tin, skopeo là lựa chọn của dân chuyên nghiệp. Nó cho phép bạn kiểm tra các image từ xa mà không cần tải xuống toàn bộ tệp nặng hơn 500MB. Nó hiển thị chính xác kiến trúc và tag nào đang khả dụng.
# Cài đặt qua: brew install skopeo hoặc sudo apt install skopeo
skopeo inspect docker://docker.io/library/nginx:latest
6. Khắc phục sự cố trên Private Registry (ECR/Harbor/Nexus)Nếu bạn làm việc trong môi trường doanh nghiệp, vấn đề có thể liên quan đến quyền truy cập hoặc đồng bộ hóa. Trên AWS ECR, hãy xác minh rằng chính sách IAM của bạn bao gồm ecr:BatchGetImage. Đối với Harbor hoặc Nexus, tác vụ 'Garbage Collection' có thể đã xóa một chỉ mục manifest trong khi image đang được push. Trong những trường hợp này, cách khắc phục đáng tin cậy nhất thường là build lại và push lại image:
docker build -t private-reg.com/app:v1.0.5 .
docker push private-reg.com/app:v1.0.5
Xác minhKhắc phục thành công sẽ giúp quá trình pull diễn ra trơn tru. Bạn sẽ thấy mã băm digest và trạng thái 'Downloaded newer image':
$ docker pull alpine:3.19
3.19: Pulling from library/alpine
Digest: sha256:c5b1261d...
Trạng thái: Đã tải xuống image mới hơn cho alpine:3.19
Mẹo chuyên nghiệp cho quy trình làm việc- Cố định phiên bản: Đừng sử dụng :latest trong Dockerfile của bạn. Nó làm cho quá trình build không thể dự đoán trước và dẫn đến các lỗi manifest này.- Tự động hóa việc gắn tag 'latest': Nếu bạn muốn :latest hoạt động, hãy cập nhật pipeline CI/CD (GitHub Actions, GitLab CI) để push đồng thời hai tag: tag phiên bản và tag latest.- Dọn dẹp metadata cục bộ: Nếu bạn nghi ngờ Docker daemon cục bộ đang bị lỗi, hãy chạy docker system prune để xóa cache và thử lại.
