From 1ce0e84989f8e29161ea30bc8ef7a217ebab68c0 Mon Sep 17 00:00:00 2001 From: Leandro Damascena Date: Mon, 18 Aug 2025 11:28:53 +0100 Subject: [PATCH 1/2] Adding troubleshooting page --- docs/build_recipes/troubleshooting.md | 79 +++++++++++++++++++ .../troubleshooting/debug-import-errors.sh | 12 +++ .../fix-architecture-mismatch.sh | 8 ++ .../fix-build-inconsistencies.sh | 18 +++++ .../fix-layer-compatibility.sh | 12 +++ .../troubleshooting/optimize-cold-starts.sh | 13 +++ .../troubleshooting/optimize-package-size.sh | 14 ++++ mkdocs.yml | 2 + 8 files changed, 158 insertions(+) create mode 100644 docs/build_recipes/troubleshooting.md create mode 100644 examples/build_recipes/troubleshooting/debug-import-errors.sh create mode 100644 examples/build_recipes/troubleshooting/fix-architecture-mismatch.sh create mode 100644 examples/build_recipes/troubleshooting/fix-build-inconsistencies.sh create mode 100644 examples/build_recipes/troubleshooting/fix-layer-compatibility.sh create mode 100644 examples/build_recipes/troubleshooting/optimize-cold-starts.sh create mode 100644 examples/build_recipes/troubleshooting/optimize-package-size.sh diff --git a/docs/build_recipes/troubleshooting.md b/docs/build_recipes/troubleshooting.md new file mode 100644 index 00000000000..aece222f746 --- /dev/null +++ b/docs/build_recipes/troubleshooting.md @@ -0,0 +1,79 @@ +--- +title: Troubleshooting +description: Common issues and solutions when building Lambda packages +--- + + + +## 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:** + ```bash + --8<-- "examples/build_recipes/troubleshooting/optimize-package-size.sh" + ``` + +### Import and runtime errors + +???+ error "ModuleNotFoundError or ImportError" + **Symptoms:** + - `ModuleNotFoundError: No module named 'aws_lambda_powertools'` + - Function fails at runtime with import errors + + **Solutions:** + ```bash + --8<-- "examples/build_recipes/troubleshooting/debug-import-errors.sh" + ``` + +???+ error "Architecture mismatch errors" + **Symptoms:** + - `ImportError: /lib64/libc.so.6: version GLIBC_2.XX not found` + - Compiled extensions fail to load + + **Solutions:** + ```bash + --8<-- "examples/build_recipes/troubleshooting/fix-architecture-mismatch.sh" + ``` + +### Performance issues + +???+ warning "Slow cold starts" + **Symptoms:** + - High initialization duration in CloudWatch logs + - Timeouts on first invocation + + **Solutions:** + ```bash + --8<-- "examples/build_recipes/troubleshooting/optimize-cold-starts.sh" + ``` + +### Build and deployment issues + +???+ error "Build inconsistencies across environments" + **Symptoms:** + - Works locally but fails in CI/CD + - Different behavior between team members + + **Solutions:** + ```bash + --8<-- "examples/build_recipes/troubleshooting/fix-build-inconsistencies.sh" + ``` + +???+ error "Layer compatibility issues" + **Symptoms:** + - Layer not found or incompatible runtime + - Version conflicts between layer and function dependencies + + **Solutions:** + ```bash + --8<-- "examples/build_recipes/troubleshooting/fix-layer-compatibility.sh" + ``` diff --git a/examples/build_recipes/troubleshooting/debug-import-errors.sh b/examples/build_recipes/troubleshooting/debug-import-errors.sh new file mode 100644 index 00000000000..4168ebb7bf6 --- /dev/null +++ b/examples/build_recipes/troubleshooting/debug-import-errors.sh @@ -0,0 +1,12 @@ +#!/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')" diff --git a/examples/build_recipes/troubleshooting/fix-architecture-mismatch.sh b/examples/build_recipes/troubleshooting/fix-architecture-mismatch.sh new file mode 100644 index 00000000000..284e52b3526 --- /dev/null +++ b/examples/build_recipes/troubleshooting/fix-architecture-mismatch.sh @@ -0,0 +1,8 @@ +#!/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] diff --git a/examples/build_recipes/troubleshooting/fix-build-inconsistencies.sh b/examples/build_recipes/troubleshooting/fix-build-inconsistencies.sh new file mode 100644 index 00000000000..25a927e0c68 --- /dev/null +++ b/examples/build_recipes/troubleshooting/fix-build-inconsistencies.sh @@ -0,0 +1,18 @@ +#!/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 diff --git a/examples/build_recipes/troubleshooting/fix-layer-compatibility.sh b/examples/build_recipes/troubleshooting/fix-layer-compatibility.sh new file mode 100644 index 00000000000..a7493a56a9a --- /dev/null +++ b/examples/build_recipes/troubleshooting/fix-layer-compatibility.sh @@ -0,0 +1,12 @@ +#!/bin/bash +# 1. Use correct layer ARN for your region and Python version +# Check: https://docs.powertools.aws.dev/lambda/python/latest/#lambda-layer + +# 2. Verify layer compatibility +aws lambda get-layer-version \ + --layer-name AWSLambdaPowertoolsPythonV3-python313-x86_64 \ + --version-number 22 + +# 3. Avoid version conflicts +# Don't include Powertools for AWS in deployment package if using layer +pip install pydantic requests -t build/ # Exclude powertools diff --git a/examples/build_recipes/troubleshooting/optimize-cold-starts.sh b/examples/build_recipes/troubleshooting/optimize-cold-starts.sh new file mode 100644 index 00000000000..cdfeeff858b --- /dev/null +++ b/examples/build_recipes/troubleshooting/optimize-cold-starts.sh @@ -0,0 +1,13 @@ +#!/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 + +# 4. Minimize imports in handler +# Import only what you need, avoid heavy imports at module level diff --git a/examples/build_recipes/troubleshooting/optimize-package-size.sh b/examples/build_recipes/troubleshooting/optimize-package-size.sh new file mode 100644 index 00000000000..597ceafe227 --- /dev/null +++ b/examples/build_recipes/troubleshooting/optimize-package-size.sh @@ -0,0 +1,14 @@ +#!/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 diff --git a/mkdocs.yml b/mkdocs.yml index bfcee3c8924..beab6bc0951 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,7 @@ nav: - build_recipes/index.md - Getting started: build_recipes/getting-started.md - CI/CD integration: build_recipes/cicd-integration.md + - Troubleshooting: build_recipes/troubleshooting.md - Upgrade guide: upgrade.md - We Made This (Community): we_made_this.md - Roadmap: roadmap.md @@ -242,6 +243,7 @@ plugins: - build_recipes/index.md - build_recipes/getting-started.md - build_recipes/cicd-integration.md + - build_recipes/troubleshooting.md - mkdocstrings: default_handler: python From ef241df68a0cf075bb5a72ea350ba52914f0f2bf Mon Sep 17 00:00:00 2001 From: Leandro Damascena Date: Mon, 18 Aug 2025 11:57:28 +0100 Subject: [PATCH 2/2] Adding troubleshooting page --- .../build_recipes/troubleshooting/fix-layer-compatibility.sh | 3 ++- .../build_recipes/troubleshooting/optimize-cold-starts.sh | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/examples/build_recipes/troubleshooting/fix-layer-compatibility.sh b/examples/build_recipes/troubleshooting/fix-layer-compatibility.sh index a7493a56a9a..5e12b6c4166 100644 --- a/examples/build_recipes/troubleshooting/fix-layer-compatibility.sh +++ b/examples/build_recipes/troubleshooting/fix-layer-compatibility.sh @@ -5,7 +5,8 @@ # 2. Verify layer compatibility aws lambda get-layer-version \ --layer-name AWSLambdaPowertoolsPythonV3-python313-x86_64 \ - --version-number 22 + --version-number 22 \ + --region-name {REGION} # 3. Avoid version conflicts # Don't include Powertools for AWS in deployment package if using layer diff --git a/examples/build_recipes/troubleshooting/optimize-cold-starts.sh b/examples/build_recipes/troubleshooting/optimize-cold-starts.sh index cdfeeff858b..cdedbe073b4 100644 --- a/examples/build_recipes/troubleshooting/optimize-cold-starts.sh +++ b/examples/build_recipes/troubleshooting/optimize-cold-starts.sh @@ -2,12 +2,13 @@ # 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 +# 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 + --provisioned-concurrency-config ProvisionedConcurrencyCount=10 \ + --region-name {REGION} # 4. Minimize imports in handler # Import only what you need, avoid heavy imports at module level