🚨 AWS CDK Error: 'Cannot find asset at /path/cdk.out/asset.<hash>' — Cause, Fix, and Troubleshooting Guide

Overview

This error means the cloud assembly (cdk.out) references an asset directory — a Lambda bundle, a Docker context, a file asset — that no longer exists on disk at deploy time. CDK synth writes an asset manifest that points at cdk.out/asset.<hash>, and cdk deploy (or cdk-assets) later tries to stage/upload it. If that folder was deleted, never produced, or lives in a different workspace than the one deploying, staging fails.

You will see this during deploy or asset publishing:

❌  MyAppStack failed: Error: Cannot find asset at /home/runner/work/app/cdk.out/asset.9f8e7d6c5b4a3210fedcba9876543210
    at AssetManifestBuilder ...
    at ContainerImageAssetHandler ...

It is almost always a workflow problem, not a code bug: the synthesized cdk.out and the assets it references got out of sync. This is extremely common in CI where synth and deploy run in separate jobs or containers.

Symptoms

• Deploy fails with Cannot find asset at .../cdk.out/asset.<hash>.
• The hash in the path does not correspond to any folder currently in cdk.out.
• cdk synth locally works, but the CI cdk deploy step fails.
• It breaks after adding a cdk.out entry to .gitignore or clearing a build cache.

cdk deploy --app cdk.out MyAppStack

Cannot find asset at /home/runner/work/app/cdk.out/asset.9f8e7d6c5b4a3210fedcba9876543210

Common Root Causes

1. Deploying a pre-synthesized cloud assembly without the assets

Passing --app cdk.out (or --app "path/to/assembly") deploys a frozen assembly. If only the JSON templates were carried between CI stages and the asset.* folders were dropped, staging cannot find them.

cdk synth   # job 1 produces cdk.out/
# artifact upload only kept *.template.json, not asset.* dirs
cdk deploy --app cdk.out   # job 2 -> Cannot find asset

2. Synth was never run (or run in a different directory)

Deploying against a stale or empty cdk.out from a previous, unrelated build.

cdk.out/ exists but contains an old assembly; hashes no longer match

3. cdk.out cleared between synth and deploy

A rm -rf cdk.out, a git clean, or a container that doesn’t persist the working directory removes the asset folders.

4. Asset produced by bundling that failed silently

If a Lambda NodejsFunction/PythonFunction bundling step errored but synth still emitted a manifest entry, the referenced asset.<hash> directory is absent.

5. Path or workspace mismatch (monorepo / relative paths)

Synth ran in packages/app writing absolute paths into the manifest, but deploy runs from the repo root, so the recorded /path/cdk.out/asset.<hash> no longer resolves.

How to Diagnose

Inspect what the manifest expects vs what exists

cat cdk.out/manifest.json | grep -o 'asset\.[a-f0-9]*' | sort -u
ls -d cdk.out/asset.* 2>/dev/null

Any hash in the manifest without a matching directory is your missing asset.

Confirm you are deploying the assembly you just synthed

cdk synth --quiet
cdk deploy MyAppStack   # no --app: forces a fresh synth

If a fresh synth+deploy works but --app cdk.out fails, the frozen assembly is the problem.

Check the assets manifest directly

cat cdk.out/MyAppStack.assets.json

This lists source.path for each asset — verify those paths exist.

In CI, list the artifact contents

find cdk.out -maxdepth 1 -type d -name 'asset.*' | wc -l

A count of 0 in the deploy job confirms assets were stripped from the artifact.

Fixes

Fix A: carry the entire cdk.out between CI stages

When splitting synth and deploy into separate jobs, upload/download the whole cdk.out directory, including every asset.* folder — not just the templates.

# upload after synth
- uses: actions/upload-artifact@v4
  with:
    name: cloud-assembly
    path: cdk.out          # entire directory, includes asset.* dirs
    include-hidden-files: true

Fix B: synth and deploy in the same job

The simplest fix — let cdk deploy synth for you so assets are always fresh.

cdk deploy --require-approval never MyAppStack

Fix C: clean, then rebuild the assembly

Stale hashes disappear once you regenerate.

rm -rf cdk.out
cdk synth
cdk deploy MyAppStack

Fix D: make bundling failures fatal

Ensure bundling actually produced output before deploy. For NodejsFunction, verify esbuild is installed and check synth logs for bundling errors instead of ignoring them.

npx cdk synth --verbose 2>&1 | grep -i bundl

Fix E: keep paths stable in monorepos

Always run synth and deploy from the same working directory, and prefer --output to pin a consistent assembly location.

cdk synth --output /workspace/cdk.out
cdk deploy --app /workspace/cdk.out MyAppStack

What to Watch Out For

• cdk.out is a build artifact — treat it as immutable once synthed; never hand-edit it.
• Do not commit cdk.out to git; carry it as a CI artifact instead.
• Docker-context assets can be large; some artifact uploaders skip files over a size limit — verify the folder actually transferred.
• cdk deploy without --app re-synths and can mask the issue locally; reproduce CI by explicitly passing --app cdk.out.
• Symlinks inside asset staging directories may not survive artifact zip/unzip; prefer real files.

Related Guides

• AWS CDK: Has the environment been bootstrapped?
• AWS CDK Duplicate Construct ID Error
• IaC Testing Strategies That Actually Work