🚨 AWS CDK Error: 'This CDK CLI is not compatible with the CDK library used by your application' — Cause, Fix, and Troubleshooting Guide

Overview

CDK has two independently versioned pieces: the CLI (aws-cdk, the cdk command) and the construct library (aws-cdk-lib) your app imports. When you synthesize, the library writes a cloud assembly whose manifest.json declares a schema version. The CLI reads that manifest. If the library is newer than the CLI, the CLI encounters a schema version it does not understand and refuses to proceed.

You will see this on cdk synth, cdk deploy, or cdk diff:

❌  This CDK CLI is not compatible with the CDK library used by your application.
Please upgrade the CLI to the latest version.
(Cloud assembly schema version mismatch: Maximum schema version supported is 30.0.0,
but found 39.0.0)

The direction matters: the CLI can read assemblies from older or equal libraries, but not from a newer one. So the fix is almost always “upgrade the CLI” (or, less ideally, pin the library back down). This bites teams where the CLI is installed globally and rarely updated while aws-cdk-lib is bumped by Dependabot.

Symptoms

• Every CDK command fails with Cloud assembly schema version mismatch.
• The message reports Maximum schema version supported is X (CLI) vs found Y (library), where Y > X.
• A global cdk works on one project but not another that upgraded aws-cdk-lib.
• CI passes because it uses npx cdk; a developer’s global CLI fails.

cdk synth

This CDK CLI is not compatible with the CDK library used by your application.
Please upgrade the CLI to the latest version.

Common Root Causes

1. Global CLI older than the project’s aws-cdk-lib

The classic case: npm i -g aws-cdk months ago, then aws-cdk-lib was upgraded in the project.

cdk --version
npm ls aws-cdk-lib

cdk 2.120.0 (build ...)
aws-cdk-lib@2.160.0

2. Mixed local vs global invocation

npx cdk uses the project’s dev-dependency CLI; a bare cdk uses the global one. They can be different versions, so the error appears intermittently depending on how you invoke it.

3. CI cache pinned to an old CLI

A cached global install or a Docker base image ships an old aws-cdk while the lockfile pulls a newer aws-cdk-lib.

4. Deploying a pre-synthed assembly with an old CLI

cdk deploy --app cdk.out where the assembly was produced by a newer toolchain than the CLI running the deploy.

5. Monorepo version drift

Multiple packages resolving different aws-cdk/aws-cdk-lib versions through hoisting, so the effective CLI and library mismatch.

How to Diagnose

Print both versions side by side

cdk --version
npm ls aws-cdk aws-cdk-lib

If aws-cdk (CLI) is lower than aws-cdk-lib, that is the mismatch.

Read the schema numbers from the assembly

cat cdk.out/manifest.json | grep version

Compare the version there to the CLI’s maximum supported schema in the error message.

Determine which cdk binary is on PATH

which cdk
npx cdk --version

A gap between which cdk (global) and npx cdk (local) confirms invocation drift.

Fixes

Fix A (preferred): upgrade the CLI to match or exceed the library

npm i -g aws-cdk@latest
cdk --version

Then re-run. The CLI only needs to be greater than or equal to the library’s schema version.

Fix B: always invoke the project-local CLI

Add aws-cdk as a dev dependency and call it via npx/scripts so CLI and library upgrade together in the lockfile.

npm i -D aws-cdk@latest
npx cdk synth

// package.json
"scripts": {
  "cdk": "cdk",
  "deploy": "cdk deploy"
}

Now npm run deploy guarantees the matching CLI.

Fix C: pin the library down (temporary)

If you cannot upgrade the CLI right now, hold aws-cdk-lib at a version whose schema the CLI supports.

npm i aws-cdk-lib@2.120.0

Treat this as a stopgap; upgrading the CLI is the real fix.

Fix D: refresh the CI CLI

Pin aws-cdk in the CI install step and bust any cached global install.

- run: npm ci
- run: npx cdk deploy --require-approval never

What to Watch Out For

• The compatibility is one-directional: a newer CLI reads older assemblies fine, so keeping the CLI ahead of aws-cdk-lib is always safe.
• Prefer npx cdk over a global cdk to eliminate drift permanently — the version then lives in your lockfile.
• Dependabot/renovate PRs that bump aws-cdk-lib should also bump the aws-cdk dev dependency; configure them to group both.
• Do not downgrade aws-cdk-lib in production just to satisfy an old laptop CLI; upgrade the laptop.
• After upgrading the CLI, re-cdk synth from scratch so a stale cdk.out doesn’t mask the fix.

Related Guides

• AWS CDK: Has the environment been bootstrapped?
• AWS CDK Duplicate Construct ID Error
• AWS CDK ‘Cannot find asset at cdk.out/asset.’