問題の発生誰もが一度は経験することです。標準的な docker pull を実行した際、プログレスバーが表示される代わりに「manifest unknown」エラーに遭遇することがあります。これは通常、Docker デーモンがリポジトリは見つけたものの、要求された特定のバージョンを見つけられない場合に発生します。エラーメッセージが曖昧なため、イメージが実在するのかどうかさえ分からず、フラストレーションが溜まる原因となります。
Error response from daemon: manifest for <image>:<tag> not found: manifest unknown: manifest unknown
エラーが発生する理由このエラーは、本質的にあなたのリクエストとレジストリに保存されている内容との間に不一致があることを意味します。主な原因は以下の通りです：
- タイポ（入力ミス）： ハイフンの位置が一つ違ったり、大文字であるべき場所が小文字になっていたりするだけで、リクエストは失敗します。- 'latest' の罠： Docker はタグを指定しない場合、デフォルトで
:latest を使用します。しかし、多くの現代的な CI/CD パイプラインでは、イメージに v1.2.0 や Git のコミット SHA などのバージョン番号のみをタグ付けし、latest タグを空のままにしていることがよくあります。- アーキテクチャの不一致： 例えば、M2 Mac を使用していて、amd64 のみをサポートするイメージをプルしようとした場合です。レジストリに特定のハードウェア用のマニフェストがない場合、このエラーが返されることがあります。- レジストリの同期問題： Harbor や Nexus などのプライベートレジストリでは、メタデータの破損やプッシュの中断により、イメージが存在するように見えても有効なマニフェストがない「ゴースト」イメージが発生することがあります。## 解決方法### 1. タグが存在するか確認するリポジトリが存在するからといって、タグも存在すると決めつけないでください。まずレジストリの UI を確認しましょう。公開イメージの場合は、Docker Hub にアクセスし、「Tags」タブで目的のイメージを検索してください。
コマンドラインを好む場合は、レジストリ API に直接問い合わせることもできます。例えば、公式の Python イメージのタグを確認するには以下のようになります：
curl -L -s 'https://registry.hub.docker.com/v2/repositories/library/python/tags?page_size=5' | jq '."results"[].name'
2. 大文字・小文字に注意するDocker のタグは厳密に大文字・小文字を区別します。人間には my-image:Beta と my-image:beta が同じに見えても、Docker デーモンはこれらを全く別のエンティティとして扱います。プルコマンドがレジストリの表記と完全に一致しているか確認してください。
3. 'latest' ではなくバージョンを指定するデフォルトのタグに頼ることは、よくある落とし穴です。チームがセマンティックバージョニングを使用している場合は、特定のバージョンをプルしてみてください。例えば、docker pull node の代わりに、特定の安定版を指定します：
docker pull node:20.11-bookworm-slim
4. プラットフォームのアーキテクチャを強制するApple Silicon (M1/M2/M3) や ARM ベースのクラウドサーバーの普及により、アーキテクチャの不一致が多発しています。Mac を使用していて、イメージが Intel/AMD64 サーバー用にしかビルドされていない場合、Docker は一致するマニフェストを見つけられないことがあります。この場合、プラットフォームを強制することで解決できることがよくあります：
docker pull --platform linux/amd64 mysql:8.0
5. Skopeo を使用して詳細に調査するDocker CLI では十分な情報が得られない場合、プロは skopeo を選択します。これを使用すると、500MB 以上あるファイル全体をダウンロードすることなく、リモートイメージを検査できます。どのアーキテクチャとタグが利用可能かを正確に表示してくれます。
# インストール方法: brew install skopeo または sudo apt install skopeo
skopeo inspect docker://docker.io/library/nginx:latest
6. プライベートレジストリ（ECR/Harbor/Nexus）のトラブルシューティング企業環境で作業している場合、権限や同期に関連する問題である可能性があります。AWS ECR の場合、IAM ポリシーに ecr:BatchGetImage が含まれていることを確認してください。Harbor や Nexus の場合、イメージのプッシュ中に「ガベージコレクション（Garbage Collection）」タスクが実行され、マニフェストインデックスがクリアされた可能性があります。このような場合、最も確実な修正方法はイメージを再ビルドして再プッシュすることです：
docker build -t private-reg.com/app:v1.0.5 .
docker push private-reg.com/app:v1.0.5
確認方法修正が成功すると、正常にプルが完了します。ダイジェストハッシュと「Downloaded newer image」というステータスが表示されるはずです：
$ docker pull alpine:3.19
3.19: Pulling from library/alpine
Digest: sha256:c5b1261d...
Status: Downloaded newer image for alpine:3.19
ワークフローのためのプロのヒント- バージョンを固定する： Dockerfile で :latest を使用するのはやめましょう。ビルドが予測不能になり、今回のようなマニフェストエラーの原因となります。- 'latest' タグ付けを自動化する： :latest を機能させたい場合は、CI/CD パイプライン（GitHub Actions, GitLab CI）を更新して、バージョンタグと latest タグの両方を同時にプッシュするように設定します。- ローカルメタデータのクリーンアップ： ローカルの Docker デーモンに問題があると思われる場合は、docker system prune を実行してキャッシュをクリアしてから再試行してください。
