## Common issues and solutions

This section covers the most frequent issues encountered when building and deploying Lambda functions with Powertools for AWS Lambda (Python). Each issue includes symptoms to help identify the problem and practical solutions with working code examples.

### Package size issues

> [!WARNING]
>
> **Lambda deployment package too large (\>50MB unzipped)**
>
> **Symptoms:** - `RequestEntityTooLargeException` during deployment - Slow cold starts - High memory usage
>
> **Solutions:**
>
> ```
> #!/bin/bash
> # 1. Use Lambda Layers for heavy dependencies
> pip install aws-lambda-powertools[all] -t layers/powertools/python/
>
> # 2. Remove unnecessary files
> find build/ -name "*.pyc" -delete
> find build/ -name "__pycache__" -type d -exec rm -rf {} +
> find build/ -name "tests" -type d -exec rm -rf {} +
>
> # 3. Strip debug symbols from compiled libraries
> find build/ -name "*.so" -exec strip --strip-debug {} \;
>
> # 4. Use container images for very large packages
> # Deploy as container image instead of ZIP
> ```

### Import and runtime errors

> [!CAUTION]
>
> **ModuleNotFoundError or ImportError**
>
> **Symptoms:** - `ModuleNotFoundError: No module named 'aws_lambda_powertools'` - Function fails at runtime with import errors
>
> **Solutions:**
>
> ```
> #!/bin/bash
> # 1. Verify dependencies are in the package
> unzip -l lambda-package.zip | grep powertools
>
> # 2. Check Python path in Lambda
> python -c "import sys; print(sys.path)"
>
> # 3. Ensure platform compatibility
> pip install --platform manylinux2014_x86_64 --only-binary=:all: aws-lambda-powertools[all]
>
> # 4. Test imports locally
> cd build && python -c "from aws_lambda_powertools import Logger; print('OK')"
> ```

> [!CAUTION]
>
> **Architecture mismatch errors**
>
> **Symptoms:** - `ImportError: /lib64/libc.so.6: version GLIBC_2.XX not found` - Compiled extensions fail to load
>
> **Solutions:**
>
> ```
> #!/bin/bash
> # Use Docker with Lambda base image
> docker run --rm -v "$PWD":/var/task public.ecr.aws/lambda/python:3.13 \
>     pip install aws-lambda-powertools[all] -t /var/task/
>
> # Or force Linux-compatible wheels
> pip install --platform manylinux2014_x86_64 --implementation cp \
>     --python-version 3.13 --only-binary=:all: aws-lambda-powertools[all]
> ```

### Performance issues

> [!WARNING]
>
> **Slow cold starts**
>
> **Symptoms:** - High initialization duration in CloudWatch logs - Timeouts on first invocation
>
> **Solutions:**
>
> ```
> #!/bin/bash
> # 1. Optimize package size (see above)
>
> # 2. Use public Powertools for AWS layer
> # Layer ARN: arn:aws:lambda:{REGION}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:1
>
> # 3. Enable provisioned concurrency for critical functions
> aws lambda put-provisioned-concurrency-config \
>     --function-name my-function \
>     --provisioned-concurrency-config ProvisionedConcurrencyCount=10 \
>     --region-name {REGION}
>
> # 4. Minimize imports in handler
> # Import only what you need, avoid heavy imports at module level
> ```

### Build and deployment issues

> [!CAUTION]
>
> **Build inconsistencies across environments**
>
> **Symptoms:** - Works locally but fails in CI/CD - Different behavior between team members
>
> **Solutions:**
>
> ```
> #!/bin/bash
> # 1. Use lock files for reproducible builds
> # Poetry: poetry.lock
> # uv: uv.lock
> # pip: requirements.txt with pinned versions
>
> # 2. Use Docker for consistent build environment
> docker run --rm -v "$PWD":/app -w /app python:3.13-slim \
>     bash -c "pip install -r requirements.txt -t build/"
>
> # 3. Pin all tool versions
> pip==24.0
> poetry==1.8.0
> uv==0.1.0
>
> # 4. Use same Python version everywhere
> python-version: '3.13'  # In CI/CD
> python = "^3.13"        # In pyproject.toml
> ```

> [!CAUTION]
>
> **Layer compatibility issues**
>
> **Symptoms:** - Layer not found or incompatible runtime - Version conflicts between layer and function dependencies
>
> **Solutions:**
>
> ```
> #!/bin/bash
> # 1. Use correct layer ARN for your region and Python version
> # Check: https://docs.aws.amazon.com/powertools/python/latest/#lambda-layer
>
> # 2. Verify layer compatibility
> aws lambda get-layer-version \
>     --layer-name AWSLambdaPowertoolsPythonV3-python313-x86_64 \
>     --version-number 22 \
>     --region-name {REGION}
>
> # 3. Avoid version conflicts
> # Don't include Powertools for AWS in deployment package if using layer
> pip install pydantic requests -t build/  # Exclude powertools
> ```