Troubleshooting#

Common issues and their solutions when using core-aws-cdk.

Installation Issues#

Issue: “Too many open files”#

Problem: Error when running tests in parallel.

Solution: Reduce number of parallel workers:

pytest -n 2  # Instead of -n auto

AWS Deployment Issues#

Issue: AWS rate limiting#

Problem: Tests fail with rate limiting errors.

Solution: Run functional tests sequentially or with limited parallelism:

pytest tests/functional/  # Sequential
# or
pytest tests/functional/ -n 2  # Limited parallelism

Issue: Tests hanging#

Problem: Tests appear to hang during CDK deployment.

Solution: Check CDK CLI timeouts. Current timeout is 600s (10 minutes). If deployments take longer, increase the timeout in your test configuration.

Issue: CDK version mismatch#

Problem: Error message about schema version mismatch.

Solution: Ensure CDK CLI version matches library version:

npm install -g aws-cdk@latest
cdk --version

The library requires aws-cdk-lib>=2.195.0.

Issue: Node.js version warning#

Problem: Warning about unsupported Node.js version.

Solution: Ensure Node.js v20 or v22 is installed and accessible:

node --version
which node

If using NVM:

nvm install 20
nvm use 20

Lambda Packaging Issues#

Issue: Missing dependencies in package#

Problem: Lambda function fails with import errors.

Solution: Create requirements.txt in your Lambda directory:

cd /path/to/lambda
echo "requests>=2.28.0" > requirements.txt
python test.py

Issue: Package too large#

Problem: Lambda deployment fails due to package size.

Solution 1: Exclude unnecessary files:

result = ZipAssetCode(
    project_directory=pathlib.Path("/path/to/project"),
    work_dir=pathlib.Path("/path/to/lambda"),
    includes=["handler.py"],  # Only include necessary files
    include_project_folders=["commons"],
    debug=False  # Disable debug for smaller package
)

Solution 2: Use Lambda layers for large dependencies:

from aws_cdk.aws_lambda import LayerVersion, Code

layer = LayerVersion(
    stack,
    "DependenciesLayer",
    code=Code.from_asset("./layer"),
    compatible_runtimes=[Runtime.PYTHON_3_12]
)

lambda_function = stack.create_lambda(
    function_id="MyFunction",
    handler="handler.lambda_handler",
    code=Code.from_asset("./lambda"),
    runtime=Runtime.PYTHON_3_12,
    layers=[layer]
)

Issue: Wrong Python version in package#

Problem: Lambda fails with Python version mismatch errors.

Solution: Ensure virtual environment matches Lambda runtime:

virtualenv --python=python3.12 .venv
source .venv/bin/activate
python test.py

Testing Issues#

Issue: Functional tests fail with permission errors#

Problem: AWS API calls fail with access denied.

Solution: Ensure AWS credentials have required permissions:

  • Lambda (create, invoke, delete)

  • S3 (create bucket, put/get objects, delete)

  • SNS (create topic, publish)

  • SQS (create queue, send/receive messages)

  • CloudFormation (create/update/delete stacks)

  • IAM (create roles and policies)

Check credentials:

aws sts get-caller-identity
aws configure list

Issue: Tests leave resources behind#

Problem: AWS resources not cleaned up after test failures.

Solution: Manually clean up resources:

# List stacks
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE

# Delete specific stack
aws cloudformation delete-stack --stack-name TestIntegrationStack

# Empty and delete S3 buckets
aws s3 rm s3://bucket-name --recursive
aws s3 rb s3://bucket-name

Issue: Import errors in tests#

Problem: Tests fail with module not found errors.

Solution: Ensure package is installed in development mode:

pip install -e ".[dev]"

Type Checking Issues#

Issue: mypy errors with CDK constructs#

Problem: Type checking fails with CDK resource types.

Solution: The project includes proper type annotations. Ensure you’re using:

from typing import Any, Optional, Dict
from constructs import Construct

If you still encounter issues, you can use type ignore comments:

resource = some_cdk_call()  # type: ignore[misc]

Documentation Issues#

Issue: Sphinx build fails#

Problem: Documentation build fails with import errors.

Solution: Install documentation dependencies:

cd docs
pip install -r requirements.txt
make html

Issue: API documentation not generated#

Problem: Module documentation is empty in Sphinx build.

Solution: Ensure modules have proper docstrings and are importable:

# Module-level docstring required
"""Module description here."""

class MyClass:
    """Class description here."""

    def my_method(self) -> None:
        """Method description here."""
        pass

Performance Issues#

Issue: Slow test execution#

Solution: Use parallel execution:

# For unit tests (safe)
pytest tests/unit/ -n auto

# For functional tests (use limited parallelism)
pytest tests/functional/ -n 2

Issue: Slow CDK synthesis#

Solution:

  1. Reduce number of stacks being synthesized

  2. Use CDK context to cache values

  3. Minimize cross-stack references

Getting Help#

If you encounter an issue not covered here:

  1. Check the GitHub Issues

  2. Review the Changelog

  3. Consult the AWS CDK Documentation

  4. Open a new issue with:

    • Python version

    • CDK version (cdk --version)

    • Node.js version (node --version)

    • Error message and full traceback

    • Minimal reproduction steps