diff --git a/content/en/user-guide/integrations/aws-cdk/index.md b/content/en/user-guide/integrations/aws-cdk/index.md
index 68dc2c9da3..e1e71c3f19 100644
--- a/content/en/user-guide/integrations/aws-cdk/index.md
+++ b/content/en/user-guide/integrations/aws-cdk/index.md
@@ -96,6 +96,27 @@ By default, stacks with validated certificates may not be deployed using the `lo
 This originates from the way how CDK ensures the certificate is ready - it creates a single-file lambda function with a single dependency on `aws-sdk` which is usually preinstalled and available globally in lambda runtime.
 When this lambda is executed locally from the `/tmp` folder, the package can not be discovered by Node due to the way how Node package resolution works.
 
+## CDK Version Compatibility
+
+`cdklocal` works with all installed versions of the Node.js `aws-cdk` package.
+However, issues exist for `aws-cdk >= 2.177.0`.
+
+For these versions:
+
+* We unset AWS-related environment variables like `AWS_PROFILE` before calling `cdk`.
+* We explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to point to LocalStack.
+
+Some environment variables may cause conflicting config, such as wrong region or accidental deploys to real AWS.
+To allow specific variables (e.g., `AWS_REGION`), use `AWS_ENVAR_ALLOWLIST`:
+
+```bash
+AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...
+```
+
+If you manually set `AWS_ENDPOINT_URL`, it will be used.
+You must also set `AWS_ENDPOINT_URL_S3`, and it must include `.s3.` to correctly identify S3 API calls.
+See full configuration details [on our configuration docs](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations).
+
 ## Other resources
 
 * [Hot-reloading Lambda functions with CDK]({{< ref "user-guide/lambda-tools/hot-reloading#aws-cloud-development-kit-cdk-configuration" >}})