はじめに
AWS ECS（または Fargate）で Docker イメージを使ってコンテナをデプロイしようとしたところ、次のようなエラーが発生しました。
CannotPullContainerError: pull image manifest has been retried 5 time(s):
image manifest does not contain descriptor matching platform 'linux/amd64'
これは、コンテナイメージが linux/amd64 アーキテクチャに対応していない場合に発生する典型的なエラーです。本記事では、原因と解決法を具体的に解説します。
エラーの意味
このエラーは、ECS が Docker イメージを pull（取得）しようとしたときに：
- ターゲットプラットフォーム：linux/amd64
- しかし、リモートのイメージにはそのプラットフォームに対応する descriptor（イメージ情報）が存在しなかった
という状況を表します。
つまり、イメージはあるけど、ECS が必要としているアーキテクチャ用ではない ということ。
原因
✅ よくある原因：ビルドしたイメージが linux/amd64 に対応していない
Docker イメージを docker build でビルドしただけでは、そのマシンのアーキテクチャ（たとえば M1 Mac なら arm64）に最適化されたイメージが作られます。
その結果：
- ECS（x86_64 基盤）からは 非対応のイメージに見えてしまう
- CannotPullContainerError が発生する
解決方法
✅ 解決策①：buildx を使って linux/amd64 向けにビルド＆push する
docker buildx build \
--platform linux/amd64 \
-t 127929167946.dkr.ecr.ap-northeast-1.amazonaws.com/ctn-cicd-hdon-repo:latest \
--push \
.
* --platform linux/amd64：ECS 用に x86 アーキテクチャでビルド
* --push：ECR に直接 push（これがないとマニフェストが付かない）
🔍 プラットフォーム確認コマンド
まとめ
原因
イメージが linux/amd64 に対応していない
対応
docker buildx build --platform linux/amd64 ... --push を使う
イメージが arm64 のみ ECS タスク定義で ARM64 を指定する
docker build のみでイメージを作っていた buildx を使ってプラットフォーム明示する
さいごに
このエラーはコンテナ開発初期にかなり頻繁に遭遇する落とし穴です。Docker のビルドプラットフォームと ECS の実行環境が一致しているかどうか、これを常に意識することで、トラブルを未然に防げます。