Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4133 pages
Servers, nginx and Docker

cdk synth or cdk deploy says the CLI is too old for the app's aws-cdk-lib

Your error

Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0.2 more lines it can show

Fix it fast

Most common cause, 1 of 3

The CLI is older than aws-cdk-lib

Install the latest CLI as a dev dependency of the project and always call it through npx, so the global copy does not matter.

Fix
npm install --save-dev aws-cdk@latest
npx cdk synth
Did this fix it?
Full steps for this cause: check, fix, verify

Short answer

aws-cdk-lib writes a versioned cloud assembly when it synthesizes, and the CDK CLI must understand that schema version. A CLI older than the library cannot, so synth or deploy stops. Update the CLI (the aws-cdk npm package) to the latest release, locally and in CI. Since 2025 the CLI ships separately with 2.1xxx version numbers, so do not try to match it to the library version.

  • Applies to aws-cdk-lib 2.x, aws-cdk CLI 2.1000 and later, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Which cause do you have?

Print the CLI that actually runs and the library the app uses. On a mismatch the CLI is the one to move.

Run this first
npx cdk --version
npm ls aws-cdk-lib aws-cdk
which -a cdk

Then find the line you see in this list and open its fix:

  1. 1The CLI is older than aws-cdk-libThe library was updated (often by Dependabot or npm update) and the CLI was not
  2. 2A global or CI-installed CLI shadows the project's copynpx cdk --version is new, but plain cdk --version or the CI log shows an older number
  3. 3The CLI is pinned to the library's version numberpackage.json has aws-cdk and aws-cdk-lib at the same version, for example both 2.179.0, or a range like ^2.179.0 for the CLI

What does the error look like?

  • Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0.
  • Please upgrade your CLI in order to interact with this app.
  • This CDK CLI is not compatible with the CDK library used by your application. Please upgrade the CLI to the latest version.

Cause 1 of 3

The CLI is older than aws-cdk-lib

You seeThe library was updated (often by Dependabot or npm update) and the CLI was not

Check

AWS's versioning guide says each aws-cdk-lib release works with the CLI that was current at its release and any newer CLI, and that an older CLI only works if it supports the library's cloud assembly schema. When it does not, this exact mismatch message appears.

Check
npm view aws-cdk version

Fix

Install the latest CLI as a dev dependency of the project and always call it through npx, so the global copy does not matter.

Fix
npm install --save-dev aws-cdk@latest
npx cdk synth

Verify

Synth completes and writes cdk.out without the schema error.

Verify
npx cdk synth > /dev/null && ls cdk.out/manifest.json

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

A global or CI-installed CLI shadows the project's copy

You seenpx cdk --version is new, but plain cdk --version or the CI log shows an older number

Check

Pipelines often run npm install -g aws-cdk@<old pin> or use an image with a CLI baked in. Whatever cdk comes first on PATH is what runs.

Check
grep -rnE "aws-cdk(@[0-9^~.]+)?" .github/workflows buildspec*.yml Dockerfile .gitlab-ci.yml 2>/dev/null

Fix

Drop the global install from CI and run the project's CLI, or move the pin to the latest release.

Fix
# .github/workflows/deploy.yml
- run: npm ci
- run: npx cdk deploy --require-approval never

Verify

The CI log prints the same CLI version as npx cdk --version on your machine, and the deploy step passes.

Verify
npx cdk --version

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

The CLI is pinned to the library's version number

You seepackage.json has aws-cdk and aws-cdk-lib at the same version, for example both 2.179.0, or a range like ^2.179.0 for the CLI

Check

The CLI now lives in its own repository and release line: npm shows CLI versions from 2.1000.0 upward (2.1149.0 at the time of writing) while aws-cdk-lib is at 2.277.0. A rule that keeps the two numbers equal holds the CLI back.

Check
npm view aws-cdk version
npm view aws-cdk-lib version

Fix

Version the two packages independently. A caret range on 2.1xxx keeps the CLI moving with new schema support.

Fix
// package.json
"devDependencies": {
  "aws-cdk": "^2.1149.0"
},
"dependencies": {
  "aws-cdk-lib": "^2.277.0",
  "constructs": "^10.0.0"
}

Verify

After npm install, npx cdk --version shows a 2.1xxx release and synth works.

Verify
npm install && npx cdk --version && npx cdk synth

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Let your update bot raise aws-cdk (the CLI) as well as aws-cdk-lib.
  • Use the project-local CLI through npx everywhere, never a global install.
  • Upgrade the CLI first when in doubt: AWS says a newer CLI is always safe with a supported library.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.