> ## Documentation Index
> Fetch the complete documentation index at: https://cdktn.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading to CDKTN Version 0.24

> Upgrade your CDK Terrain (cdktn) project from v0.23 to v0.24. This release requires Node.js 22.19.0, always validates Terraform function usage, preserves symlinks in assets, and switches the CLI's HTTP client to undici.

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](https://cdktn.io/docs/release/whats-new/v0-24.md).

## 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:

```bash theme={null}
node --version   # must be >= 22.19.0
```

> [!NOTE]
>
> 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](https://cdktn.io/docs/release/whats-new/v0-24/function-validation-default.md#how-to-fix-a-failure).

### Assets preserve symlinks

`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](https://cdktn.io/docs/release/whats-new/v0-24/plugin-protocol.md#write-only-attributes).

## Upgrade Process

**TypeScript/JavaScript**

**1. Ensure Node.js 22.19.0+:**

```bash theme={null}
node --version
```

**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`:

```bash theme={null}
npm view @cdktn/provider-random@15 peerDependencies
```

CDKTN 0.24 doesn't support `constructs` 10.8. If you pin `constructs`
yourself, keep it below 10.8.0:

```diff theme={null}
{
  "dependencies": {
-   "cdktn": "^0.23.4",
-   "constructs": "^10.6.0",
-   "@cdktn/provider-random": "^14.0.0"
+   "cdktn": "^0.24.0",
+   "constructs": ">=10.6.0 <10.8.0",
+   "@cdktn/provider-random": "^15.0.0"
  },
  "devDependencies": {
-   "cdktn-cli": "^0.23.4"
+   "cdktn-cli": "^0.24.0"
  }
}
```

**3. Reinstall and verify:**

```bash theme={null}
npm install
npx tsc --noEmit
```

**Python**

**1. Ensure Node.js 22.19.0+** for the CLI.

**2. Bump cdktn and your pre-built providers in requirements.txt or Pipfile:**

```diff theme={null}
- cdktn>=0.23.4
+ cdktn>=0.24.0
```

Bump each `cdktn-provider-*` package to the major built for 0.24 as well.
`cdktn` 0.24.0 requires `constructs>=10.6.0,<10.8.0`.

**3. Reinstall:**

```bash theme={null}
pip install -r requirements.txt --force-reinstall
```

**Go**

**1. Ensure Node.js 22.19.0+** for the CLI.

**2. Bump the cdktn module:**

```diff theme={null}
require (
-   github.com/open-constructs/cdk-terrain-go/cdktn v0.23.4
+   github.com/open-constructs/cdk-terrain-go/cdktn v0.24.0
)
```

**3. Tidy modules:**

```bash theme={null}
go mod tidy
```

**Java**

Ensure Node.js 22.19.0+ for the CLI, bump the dependency to `0.24.0`, and
rebuild.

```diff theme={null}
dependencies {
-   implementation "io.cdktn:cdktn:0.23.4"
+   implementation "io.cdktn:cdktn:0.24.0"
}
```

```bash theme={null}
./gradlew build
```

**C#**

Ensure Node.js 22.19.0+ for the CLI, bump the package reference to
`0.24.0`, and restore.

```diff theme={null}
<ItemGroup>
-   <PackageReference Include="Io.Cdktn" Version="0.23.4" />
+   <PackageReference Include="Io.Cdktn" Version="0.24.0" />
</ItemGroup>
```

```bash theme={null}
dotnet restore
```

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](https://cdktn.io/docs/release/whats-new/v0-24/plugin-protocol.md#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:

```bash theme={null}
# Synthesize
cdktn synth

# Verify output
ls cdktf.out/stacks/*/cdk.tf.json
```

## Getting Help

* Ask a question in [the cdk.dev Slack](https://cdk.dev/)
* GitHub Issues: [https://github.com/open-constructs/cdk-terrain/issues](https://github.com/open-constructs/cdk-terrain/issues)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.