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 showFix it fast
Most common cause, 1 of 3The 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.
npm install --save-dev aws-cdk@latest
npx cdk synthShort 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.
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.
npx cdk --version
npm ls aws-cdk-lib aws-cdk
which -a cdkThen find the line you see in this list and open its fix:
- 1The CLI is older than aws-cdk-lib
The library was updated (often by Dependabot or npm update) and the CLI was not - 2A global or CI-installed CLI shadows the project's copy
npx cdk --version is new, but plain cdk --version or the CI log shows an older number - 3The CLI is pinned to the library's version number
package.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.
npm view aws-cdk versionFix
Install the latest CLI as a dev dependency of the project and always call it through npx, so the global copy does not matter.
npm install --save-dev aws-cdk@latest
npx cdk synthVerify
Synth completes and writes cdk.out without the schema error.
npx cdk synth > /dev/null && ls cdk.out/manifest.jsonConfirmed by docs.aws.amazon.com
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.
grep -rnE "aws-cdk(@[0-9^~.]+)?" .github/workflows buildspec*.yml Dockerfile .gitlab-ci.yml 2>/dev/nullFix
Drop the global install from CI and run the project's CLI, or move the pin to the latest release.
# .github/workflows/deploy.yml
- run: npm ci
- run: npx cdk deploy --require-approval neverVerify
The CI log prints the same CLI version as npx cdk --version on your machine, and the deploy step passes.
npx cdk --versionConfirmed by docs.aws.amazon.com
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.
npm view aws-cdk version
npm view aws-cdk-lib versionFix
Version the two packages independently. A caret range on 2.1xxx keeps the CLI moving with new schema support.
// 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.
npm install && npx cdk --version && npx cdk synthConfirmed by raw.githubusercontent.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.