Skip to main content
0.24 contains breaking changes. Most projects only need a newer Node.js and the package bumps below. Read the breaking changes to check whether your project is affected. For everything v0.24 introduced, see What’s New in v0.24.

​
Breaking Changes

​
Node.js 22.19.0 minimum

cdktn-cli now requires Node.js 22.19.0 or later. This applies to every project language, because the CLI runs on Node.js. Update your local environment and CI before you upgrade:
v0.25 raises the minimum to Node.js 22.23.4. If you plan to continue to v0.25, install that version now.

​
Function validation is always on

The validateFunctionVersions feature flag is gone. Every stack now checks the functions you use through Fn against your declared targetVersions. If you don’t declare targetVersions, CDKTN checks against Terraform >=1.5.7 and OpenTofu >=1.6.0. This affects you only if you use base64gunzip, cidrcontains, convert, ephemeralasnull, issensitive, templatestring, or urldecode. If synthesis fails with Terraform function "<name>" requires ..., raise your targetVersions floor, drop the product you don’t deploy with, or stop using the function. See How to fix a failure. TerraformAsset no longer follows symlinks. Archives store symlinks as symlink entries, and DIRECTORY assets recreate them. If your asset source contains symlinks, its hash and synthesized path change once, and resources that reference the asset see a one-time update on the next deploy. Asset sources without symlinks keep their hashes. If something that consumes your assets expects real files where you have symlinks, replace those symlinks with copies in the source directory before you synthesize.

​
undici replaces node-fetch in the CLI

The CLI’s HTTP client changed. It still reads the proxy from http_proxy or HTTP_PROXY. Behind a proxy, the registry lookups that resolve pre-built provider versions on PyPI, NuGet, Maven Central, GitHub, and npm now go through it too. Make sure your proxy allows those hosts.

​
Deprecations

​
Write-only attribute getters

The pre-built providers built for 0.24 mark the getter of every write-only attribute (such as dataJsonWo on Vault’s KvSecretV2) as @deprecated. The getter always returns null, because the provider never returns a write-only value. Remove any code that reads these getters. Setting the attributes still works, but every product in your targetVersions must start at version 1.11.0 or later. See Write-only attributes.

​
Upgrade Process

1. Ensure Node.js 22.19.0+:
2. Bump the cdktn packages and your pre-built providers in package.json:Every pre-built provider was regenerated for CDKTN 0.24 and released as a new major version. For example, @cdktn/provider-random moved from 14.x to 15.x. To find the right major, check that its peerDependencies require cdktn ^0.24.0:
CDKTN 0.24 doesn’t support constructs 10.8. If you pin constructs yourself, keep it below 10.8.0:
3. Reinstall and verify:
If you generate provider bindings locally with cdktn get, regenerate them with the 0.24 CLI. To get ephemeral resources, provider-defined functions, and write-only attributes in the bindings, fetch the schema with a recent Terraform or OpenTofu binary. See Generating bindings needs a recent CLI.

​
What Stays the Same

Configuration (cdktf.json), the output directory (cdktf.out/), CDKTF_* environment variables, Terraform provider sources, and your Terraform state are unaffected. The validateFunctionVersions key can stay in cdktf.json; CDKTN ignores it.

​
Verification

After upgrading, confirm your project still synthesizes:

​
Getting Help