AWS Cloud Development Kit Core Library (v1 - Deprecated)

Common errors

• Deployment failure due to missing permissions

  cause The IAM role used by the CDK deployment or the CloudFormation execution role lacks necessary permissions for the resources being deployed.
  fix Ensure the IAM role performing the `cdk deploy` command has sufficient permissions. Check the CloudFormation Events tab in the AWS Console for specific permission errors. Follow the principle of least privilege.

• Context value not found for lookup (e.g., VPC, availability zones)

  cause CDK cannot retrieve specific environment information (e.g., existing VPC IDs) which are often fetched from your AWS account during `cdk synth`.
  fix Run `cdk context --reset` or `cdk synth` / `cdk deploy` again to refresh the context values in `cdk.context.json`. Ensure your AWS CLI is configured with correct credentials and region.

• Cyclic dependencies are not allowed

  cause Your CDK stacks have circular dependencies, meaning Stack A depends on Stack B, and Stack B simultaneously depends on Stack A.
  fix Restructure your stacks to break circular dependencies. Use `cdk.Fn.importValue` or AWS SSM Parameter Store for cross-stack references where direct dependencies are problematic.

• --app is required either in command-line in cdk.json or in ~/.cdk.json

  cause The CDK CLI cannot locate your application's entry point, typically `app.py` for Python projects.
  fix Ensure you are running `cdk` commands from the root directory of your CDK project, or explicitly specify the app entry point using `cdk synth --app 'python app.py'` (or similar for other languages).

Warnings

• breaking AWS CDK v1, including `aws-cdk-core`, reached its official end-of-support on June 1, 2023. This means it no longer receives maintenance, updates, security patches, or technical support. Continued use can expose applications to security vulnerabilities and unaddressed bugs.
  Fix: Migrate your applications to AWS CDK v2 as soon as possible. AWS provides a detailed migration guide.
• breaking Migrating from AWS CDK v1 (`aws-cdk-core`) to v2 (`aws-cdk-lib`) involves significant breaking changes. These include a consolidated single package (`aws-cdk-lib`) for stable constructs, changes in import statements, and a requirement to re-bootstrap AWS accounts with the modern bootstrap stack.
  Fix: Update `requirements.txt` to `aws-cdk-lib` and `constructs`. Adjust import statements (e.g., `from aws_cdk import App, Stack` instead of `from aws_cdk import core`). Run `cdk bootstrap` with a v2-compatible CLI. Review the official AWS CDK v2 migration guide.
• gotcha The Python version specified in `pyproject.toml` or `requirements.txt` (`~=3.7` for `aws-cdk-core`) for the CDK library itself might be different from the Python version required by the global AWS CDK CLI for optimal compatibility or newer features. For AWS CDK v2, Python 3.9 or later is required.
  Fix: Always use a supported Python version. For CDK v2, ensure Python 3.9+ is installed. It is also critical to ensure the global `aws-cdk` CLI version is compatible with your project's CDK library version, ideally keeping them in sync.
• gotcha Due to Python's dynamic typing, it's easy to pass an incorrect type of value to an AWS CDK construct, which can lead to runtime errors when the JSII layer (which translates between Python and the CDK's TypeScript core) fails.
  Fix: Leverage IDEs with good type validation support and consult CDK API documentation for expected parameter types. Implement unit tests for your constructs.
• gotcha Complex CDK applications can quickly hit AWS CloudFormation resource limits (e.g., maximum number of resources in a stack), leading to synthesis errors.
  Fix: Modularize your infrastructure into smaller, interconnected stacks. Use higher-level constructs (L2/L3 patterns) which abstract multiple underlying CloudFormation resources.

Install

• pip install aws-cdk-core==1.204.0 Install specific v1 version
• npm install -g aws-cdk@1 Install AWS CDK Toolkit (CLI) for v1

Imports

• App

  from aws_cdk import core

• Stack

  from aws_cdk import core

• Bucket
  wrong:

  from aws_cdk_lib.aws_s3 import Bucket

  correct:

  from aws_cdk.aws_s3 import Bucket

  The `aws-cdk-lib` package and its submodules are for AWS CDK v2. In CDK v1, service constructs were imported from separate `aws_cdk.aws_*` packages.

Quickstart

This quickstart demonstrates how to create a basic AWS CDK v1 application in Python, define an S3 bucket, and synthesize it into a CloudFormation template. It assumes the AWS CDK CLI (Node.js based) is already installed globally. Replace `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` with your AWS account ID and desired region, respectively. The `cdk bootstrap` command is typically a one-time setup per AWS account and region to provision resources required by the CDK.

# 1. Initialize a new CDK project (requires Node.js and 'aws-cdk' CLI installed)
# mkdir my-cdk-app
# cd my-cdk-app
# cdk init app --language python

# 2. Install dependencies
# pip install -r requirements.txt

# 3. Define a simple stack (in my_cdk_app/my_cdk_app_stack.py)
from aws_cdk import core as cdk
from aws_cdk import aws_s3 as s3

class MyCdkAppStack(cdk.Stack):
    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        s3.Bucket(self, "MyFirstBucket",
                  versioned=True,
                  bucket_name=f"my-first-cdk-bucket-{cdk.Aws.ACCOUNT_ID}")

# 4. Instantiate the app and stack (in app.py)
import os

app = cdk.App()
MyCdkAppStack(app, "MyCdkAppStack",
              env=cdk.Environment(
                  account=os.environ.get('CDK_DEFAULT_ACCOUNT', ''),
                  region=os.environ.get('CDK_DEFAULT_REGION', 'us-east-1'))
             )
app.synth() # Generates CloudFormation template

# 5. Deploy (from terminal)
# cdk bootstrap  # First-time setup per AWS account/region
# cdk deploy MyCdkAppStack