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

.. code-block:: shell

    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:

.. code-block:: shell

    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:

.. code-block:: shell

    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:

.. code-block:: shell

    node --version
    which node

..

If using NVM:

.. code-block:: shell

    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:

.. code-block:: shell

    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:

.. code-block:: python

    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:

.. code-block:: python

    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:

.. code-block:: shell

    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:

.. code-block:: shell

    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:

.. code-block:: shell

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

.. code-block:: shell

    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:

.. code-block:: python

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

..

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

.. code-block:: python

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

..

Documentation Issues
===============================================================================

Issue: Sphinx build fails
---------------------------------------

**Problem:** Documentation build fails with import errors.

**Solution:** Install documentation dependencies:

.. code-block:: shell

    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:

.. code-block:: python

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

.. code-block:: shell

    # 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 <https://gitlab.com/bytecode-solutions/core/core-aws-cdk/-/issues>`_
2. Review the `Changelog <https://gitlab.com/bytecode-solutions/core/core-aws-cdk/-/blob/master/CHANGELOG.md>`_
3. Consult the `AWS CDK Documentation <https://docs.aws.amazon.com/cdk/>`_
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