Docker のトラブルシューティング

このページでは、ジェネレーターによって生成される Docker ビルドで遭遇する可能性のある問題のトラブルシューティングガイダンスを提供します。ジェネレーターが従うパターンの背景については、Docker Bundling ガイドを参照してください。

クロスプラットフォームビルド

ts#strands-agent、py#strands-agent、ts#mcp-server、py#mcp-server などのジェネレーターは、ホストアーキテクチャに関係なく、linux/arm64（Graviton）用のイメージを生成します。x86_64 ホスト上で arm64 イメージをビルドする場合、または Apple Silicon 上で amd64 イメージをビルドする場合は、ローカルの Docker インストールでマルチプラットフォームビルドのサポートが必要です。

マルチプラットフォームビルドが設定されていない場合、症状は Dockerfile によって異なります：

Dockerfile に RUN ステップがある場合（TypeScript ジェネレーターはバンドル不可能な依存関係のために RUN npm install を実行します）：ビルドが途中で失敗し、次のエラーが表示されます
Terminal window
```
exec /bin/sh: exec format error
```
Dockerfile が COPY のみを使用する場合（Python ジェネレーター）：ビルドは成功しますが、後で docker run が次のエラーで失敗します
Terminal window
```
exec /usr/local/bin/python: exec format error
```
ベースイメージがターゲットプラットフォームで利用できない場合：FROM ステップで no match for platform in manifest というエラーでビルドが失敗します。

マルチプラットフォームビルドを有効にする

Docker Desktop（Mac / Windows / Linux）は、QEMU エミュレーションが標準で有効になっており、通常は追加のセットアップは必要ありません。

Linux ホスト（CI ランナーを含む）では、QEMU binfmt ハンドラーをカーネルに登録する必要があります。マシンごとに一度インストールしてください：

docker run --privileged --rm tonistiigi/binfmt --install all

サポートされているプラットフォームがプロジェクトのターゲットと一致することを確認します：

docker buildx inspect --bootstrap

Platforms: 行には linux/arm64 が含まれている必要があります。

エミュレートされたアーキテクチャでのビルドの遅さ

x86_64 ホスト上で arm64 イメージをビルドする場合（またはその逆）、QEMU を使用して各命令をエミュレートするため、ネイティブビルドよりも何倍も遅くなる可能性があります。ジェネレーターは、Dockerfile の外部で依存関係の解決を行うことでこれを軽減します — Docker Bundling を参照してください。それでも Docker ビルドが遅い場合：

bundle / docker ターゲットを Nx 経由で実行している（nx docker my-project）ことを確認し、実行間でバンドルがキャッシュされるようにします。
CI では、QEMU を完全に回避するために、ネイティブ ARM ランナー（例：GitHub Actions の ubuntu-24.04-arm）の使用を検討してください。

`cdk deploy` / `nx apply` 時にビルドコンテキストが見つからない

生成された docker ターゲットは、ビルドコンテキストを dist/packages/<project>/docker/...（Python）または dist/packages/<project>/bundle/...（TypeScript）に書き込み、生成された Infrastructure as Code はそのディレクトリを指しています。synth または apply を実行したときにそのディレクトリが存在しない場合、ENOENT または「directory does not exist」のようなエラーが表示されます。

ジェネレーターは docker ターゲットを build の依存関係として宣言しているため、nx build（または生成された nx deploy / nx apply ターゲット）は CDK または Terraform が実行される前にビルドコンテキストを生成します。cdk または terraform を直接呼び出す場合は、最初に docker ステップを実行してください：

nx run my-project:docker

参考資料

Docker — Multi-platform builds
Docker Bundling guide — ジェネレーターが従うパターン。