Troubleshooting Docker

This page provides troubleshooting guidance for issues you may encounter with the Docker builds produced by the generators. See the Docker Bundling guide for background on the pattern they follow.

Cross-Platform Builds

Generators such as ts#strands-agent, py#strands-agent, ts#mcp-server, and py#mcp-server produce images for linux/arm64 (Graviton), regardless of the host architecture. Building an arm64 image on an x86_64 host — or an amd64 image on Apple Silicon — requires multi-platform build support in your local Docker installation.

If multi-platform builds are not set up, the symptom depends on the Dockerfile:

Dockerfile has a RUN step (TypeScript generators RUN npm install for non-bundleable dependencies): the build fails mid-way with
Terminal window
```
exec /bin/sh: exec format error
```
Dockerfile only uses COPY (Python generators): the build succeeds, but docker run later fails with
Terminal window
```
exec /usr/local/bin/python: exec format error
```
Base image is not available for the target platform: the build fails at the FROM step with no match for platform in manifest.

Enable Multi-Platform Builds

Docker Desktop (Mac / Windows / Linux) ships with QEMU emulation enabled out of the box — no extra setup is usually required.

Linux hosts (including CI runners) need QEMU binfmt handlers registered with the kernel. Install them once per machine:

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

Verify the supported platforms match what your project targets:

docker buildx inspect --bootstrap

The Platforms: line should include linux/arm64.

Slow Builds on Emulated Architectures

Building an arm64 image on an x86_64 host (or vice versa) uses QEMU to emulate each instruction, which can be many times slower than a native build. The generators mitigate this by doing dependency resolution outside the Dockerfile — see Docker Bundling. If you are still seeing slow Docker builds:

Make sure you are running the bundle / docker targets through Nx (nx docker my-project) so the bundle is cached between runs.
On CI, consider a native ARM runner (e.g. GitHub Actions’ ubuntu-24.04-arm) to avoid QEMU entirely.

Missing Build Context at `cdk deploy` / `nx apply`

The generated docker target writes its build context to dist/packages/<project>/docker/... (Python) or dist/packages/<project>/bundle/... (TypeScript), and the generated infrastructure as code points at that directory. If that directory does not exist when you synth or apply, you will see errors like ENOENT or “directory does not exist”.

The generators declare the docker target as a dependency of build, so nx build (or the generated nx deploy / nx apply targets) will produce the build context before CDK or Terraform runs. If you invoke cdk or terraform directly, run the docker step first:

nx run my-project:docker