🚨 AWS CDK Error: 'Failed to build asset ...: docker exited with status 1' — Cause, Fix, and Troubleshooting Guide

Overview

CDK shells out to Docker in two situations: building a container image asset (DockerImageAsset, ecs.ContainerImage.fromAsset, Lambda DockerImageFunction) and bundling code assets inside a build container (aws-lambda-nodejs, aws-lambda-python, or an explicit bundling block). When the underlying docker build returns a non-zero exit code, synth aborts with this error.

You will see this during cdk synth or cdk deploy:

❌  Bundling asset MyAppStack/MyFunction/Code/Stage...
Error: Failed to build asset a1b2c3d4e5f60718293a4b5c6d7e8f90:
docker exited with status 1

The command 'docker build -t cdkasset-a1b2c3... .' returned a non-zero code: 1

The CDK message is generic; the real error is in the Docker build output printed just above it. Ninety percent of the time the fix is reading those preceding lines. The usual culprits are the Docker daemon not running, a broken Dockerfile step, a CPU-architecture mismatch, or a build that needs BuildKit/buildx.

Symptoms

• cdk synth/cdk deploy stops at Failed to build asset ...: docker exited with status 1.
• Docker build output shows a failing RUN, COPY, or apt-get/pip/npm step just above the CDK error.
• Works on a developer laptop but fails in CI (or vice versa).
• Fails on Apple Silicon or ARM runners with exec format error at runtime.

cdk synth MyAppStack

#8 ERROR: process "/bin/sh -c npm ci" did not complete successfully: exit code: 1
Error: Failed to build asset ...: docker exited with status 1

Common Root Causes

1. Docker daemon is not running or not reachable

CDK cannot talk to the Docker socket. Common in fresh CI images or after a laptop reboot.

docker info

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

2. A Dockerfile / bundling step genuinely fails

A RUN npm ci, pip install, or COPY fails — missing lockfile, unreachable package registry, or a path that isn’t in the build context.

#10 [4/6] COPY requirements.txt ./
COPY failed: file not found in build context

3. CPU architecture / platform mismatch

Building on arm64 (Apple Silicon, Graviton runners) an image intended for x86_64 Lambda/Fargate, or vice versa. The build may pass but produce an incompatible artifact, or fail on emulation.

exec /usr/bin/... : exec format error

4. BuildKit / buildx features without BuildKit enabled

Dockerfiles using --mount=type=cache, heredocs, or ARG scoping that require BuildKit fail under the legacy builder.

the --mount option requires BuildKit. Refer to https://docs.docker.com/go/buildkit/

5. Out of disk or memory during build

Large npm/pip/go build steps get OOM-killed or exhaust the runner’s disk.

npm ERR! code ENOSPC

6. Registry auth / rate limits on the base image

FROM public.ecr.aws/... or Docker Hub pulls fail on 401/429.

toomanyrequests: You have reached your pull rate limit.

How to Diagnose

Run the exact Docker build by hand

CDK prints the command; run it directly to see the full, uncollapsed output.

cd path/to/asset/context
docker build -t debug-asset .

Verify the daemon and context

docker info
docker context show

Reproduce with verbose CDK output

cdk synth MyAppStack --verbose

Scroll up from the CDK error to the first ERROR: line from the builder — that is the true failure.

Check the target architecture the construct expects

Lambda arm64 function -> image must be linux/arm64
Fargate X86_64 task    -> image must be linux/amd64

Confirm build context contents

ls -la path/to/asset/context
cat path/to/asset/context/.dockerignore

A too-aggressive .dockerignore frequently causes COPY ... file not found.

Fixes

Fix A: start Docker / point CDK at a working daemon

sudo systemctl start docker      # Linux
docker info                      # confirm it responds

On CI, ensure the job has Docker available (privileged runner, docker-in-docker, or a host socket mount).

Fix B: fix the failing Dockerfile step

Address the actual error — add the missing file to the context, fix the lockfile, or pin a working base image. Re-run docker build locally until it is green, then re-synth.

Fix C: set the platform explicitly

Pin the platform on the asset so builds are deterministic across x86 and ARM machines.

new DockerImageAsset(this, 'Image', {
  directory: path.join(__dirname, 'image'),
  platform: Platform.LINUX_AMD64, // or LINUX_ARM64 to match your Lambda/Fargate arch
});

For bundling, target the Lambda architecture:

new NodejsFunction(this, 'Fn', {
  architecture: Architecture.ARM_64,
  bundling: { forceDockerBundling: true },
});

Fix D: enable BuildKit

export DOCKER_BUILDKIT=1
cdk synth MyAppStack

Fix E: authenticate / mirror base images

Log in to ECR Public or Docker Hub before building to dodge rate limits.

aws ecr-public get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin public.ecr.aws

Fix F: give the build more room

Increase runner disk/memory, prune stale images, and add a .dockerignore to shrink the context.

docker system prune -af

What to Watch Out For

• The CDK error is a wrapper; always read the Docker output directly above it before changing anything.
• Local bundling can silently fall back when Docker is absent for some constructs but not others — do not assume “it worked locally” means CI will match.
• Set platform explicitly on every image/bundled asset; relying on the host architecture guarantees eventual exec format error surprises.
• Docker Hub anonymous pull limits will bite CI intermittently; mirror base images to ECR.
• Keep .dockerignore in sync with COPY paths — excluding a file it needs produces a confusing file not found in build context.

Related Guides

• AWS CDK: Has the environment been bootstrapped?
• AWS CDK ‘Cannot find asset at cdk.out/asset.’
• IaC Testing Strategies That Actually Work