Docker Error: manifest for image not found: manifest unknown — Решение
Архитектура Docker Registry v2 и структура OCI-манифестов
Ошибка Error response from daemon: manifest for image:tag not found: manifest unknown возвращается реестром контейнеров (Docker Hub, GitHub Packages, GitLab Registry, Harbor) при попытке выполнить docker pull или docker run. Причиной является отсутствие запрашиваемого тега (tag) в репозитории, отсутствие манифеста для целевой процессорной архитектуры хоста (например, сборка существует только для linux/amd64, а запрос идет с linux/arm64 Apple Silicon), либо удаление образа по политике ретеншена реестра.
Бизнес-риски:
Остановка пайплайнов автоматического тестирования и деплоя (CI/CD), падение масштабирования узлов Kubernetes при rolling update и срыв релизов ПО.
Таблица компонентов манифеста OCI/Docker
| Компонент | Тип медиа (MIME) | Назначение |
|---|---|---|
Fat Manifest / Index | application/vnd.oci.image.index.v1+json | Список архитектурных манифестов для разных платформ (Multi-arch). |
Image Manifest | application/vnd.docker.distribution.manifest.v2+json | Конфигурация слоев конкретной платформы (OS/Arch). |
Config Digest | SHA256 Hash | Уникальный идентификатор содержимого и переменных окружения образа. |
Пошаговая диагностика и устранение проблемы манифеста
Сценарий 1: Проверка доступных тегов в удаленном реестре
Убедитесь в правильности написания тега. Тег latest часто отсутствует у специализированных образов:
# Проверка тегов официального репозитория через curl (пример с Docker Hub API):
curl -s 'https://registry.hub.docker.com/v2/repositories/library/postgres/tags/' | jq -r '.results[].name'
# Попытка скачать образ с явным указанием конкретной версии вместо latest:
docker pull postgres:15.4-alpineСценарий 2: Принудительное указание процессорной архитектуры (--platform)
Если образ собран только под архитектуру x86_64 (AMD64), а запуск выполняется на Apple M1/M2/M3 или ARM-сервере:
# Принудительная эмуляция через QEMU с флагом --platform
docker pull --platform linux/amd64 <image_name>:<tag>
# Запуск контейнера в режиме эмуляции:
docker run --platform linux/amd64 -d <image_name>:<tag>Сценарий 3: Сборка и публикация Multi-Arch образа через buildx
Для разработчиков: создание кроссплатформенного манифеста для устранения ошибки у пользователей:
# Инициализация buildx builder
docker buildx create --use --name multiarch-builder
# Сборка и публикация образа сразу для двух платформ (amd64 и arm64)
docker buildx build --platform linux/amd64,linux/arm64 -t username/my-app:1.0.0 --push .Типовые ошибки администраторов
- Использование неявного тега 'latest': Во многих production-образах (например, Bitnami, RedHat UBI) тег latest удален ради безопасности. Всегда указывайте строгие семантические версии (например,
:1.24-alpine). - Опечатки в имени репозитория или организации: Проверьте регистр букв. Реестры Docker чувствительны к регистру (case-sensitive).
ITSTM построит отказоустойчивые Multi-Arch конвейеры сборки и внедрит надежное приватное хранилище артефактов Harbor.
Частые вопросы (FAQ)
Почему один и тот же образ качается на сервере, но падает на Mac M1?
Образ был собран без поддержки архитектуры ARM64. Используйте флаг '--platform linux/amd64' для запуска через транслятор Rosetta 2/QEMU.
Что означает статус 'manifest unknown' в приватном Harbor/Nexus?
Это означает, что образ с таким тегом был удален сборщиком мусора (Garbage Collector) или тег еще не был отправлен командой docker push.
Как скачать образ по SHA256 хэшу, если тег поврежден?
Используйте синтаксис digest: docker pull myimage@sha256:45b23d064c0dd5337e83033e122f217709828ec350cb7299c0b234d1a789da21.
Как проверить, какие архитектуры поддерживает удаленный образ?
Используйте команду: docker buildx imagetools inspect <image_name>:<tag>.
