To debug your CDKTF application, we recommend first turning on logging. Then, determine whether the issue occurs when your configuration is synthesized or when Terraform attempts to provision your infrastructure.
CDKTF_LOG_LEVEL environment variable to
debug. This produces more detailed information about each execution step. If you want to create a bug report or share the result, set
CDKTF_LOG_FILE_DIRECTORY to the file path where you want CDKTF to write the
When you run
cdktf synth, CDKTF translates your CDKTF application code into a JSON Terraform configuration file. Your application has a synth-time issue if
cdktf synth fails. Otherwise, assume the issue occurs at execution time.
When you encounter a synth issue, you must identify the construct causing the error. Check the error message for information about which construct is affected. If you cannot determine this from the error message, you must search the synthesized configuration.
We recommend repeatedly running
cdktf synth with different sections of the application file commented out until you find the error. If possible, focus your search on changes since the last time you successfully synthesized the application.
Once you find the problem, you must isolate it. If you use variables in your constructs configuration, try to temporarily replace them with static values to ensure the problem is with the construct itself. If the problem persists, examine the type to identify missing or mistyped fields. We also recommend consulting each infrastructure provider's documentation to ensure that you included all required attributes, adhered to formatting requirements, etc.
Execution-time issues happen when Terraform cannot successfully provision infrastructure with the synthesized configuration file. They can occur when you misconfigure Terraform resources in your CDKTF application, resulting in a misconfigured or incomplete Terraform configuration. They can also occur because of issues with the infrastructure provider itself.
When you encounter an execution-time issue, we recommend first examining the synthesized code. Review the Terraform documentation for the resource to see if there are misconfigured values. Remember that CDKTF renames resources and fields in most languages must be camel case, whereas Terraform uses snake case. You can also search for the resource name, Terraform, and the error to find similar issues in user forums and search the provider's Github repository for related issues.
CDKTF CLI and Library on Different Versions
We recommend keeping CDKTF CLI and the CDKTF library on the same version. A newer library version might expect the CLI to pass additional or different data to your CDKTF application. A newer CLI version might generate provider bindings in
cdktf get that rely on functionality that the older library does not support.
To check whether the versions align, run
cdktf debug. The following example output shows a case where the
cdktf-cli version (0.11.0) is newer than the
cdtf version (0.10.0).
language: typescript cdktf-cli: 0.11.0 node: v16.13.1 cdktf: 0.10.0 constructs: 10.0.63 jsii: null terraform: 1.1.8 arch: x64 os: darwin 21.4.0
The following resources can help you debug your CDKTF application:
- Ask questions in HashiCorp Discuss or in the
#terraform-cdkchannel in the cdk.dev Slack .
- Open an issue in the hashicorp/terraform-cdk repository.