GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — docs(build_recipes): add troubleshooting page (#7195) · dap0am/powertools-lambda-python@f88e8a0

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
  • docs/build_recipes
    • troubleshooting.md
  • examples/build_recipes/troubleshooting
    • debug-import-errors.sh
    • fix-architecture-mismatch.sh
    • fix-build-inconsistencies.sh
    • fix-layer-compatibility.sh
    • optimize-cold-starts.sh
    • optimize-package-size.sh
  • mkdocs.yml
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎docs/build_recipes/troubleshooting.md‎

Copy file name to clipboard
+79Lines changed: 79 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: Troubleshooting
3+
description: Common issues and solutions when building Lambda packages
4+
---
5+
6+
<!-- markdownlint-disable MD043 -->
7+
8+
## Common issues and solutions
9+
10+
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.
11+
12+
### Package size issues
13+
14+
???+ warning "Lambda deployment package too large (>50MB unzipped)"
15+
**Symptoms:**
16+
- `RequestEntityTooLargeException` during deployment
17+
- Slow cold starts
18+
- High memory usage
19+
20+
**Solutions:**
21+
```bash
22+
--8<-- "examples/build_recipes/troubleshooting/optimize-package-size.sh"
23+
```
24+
25+
### Import and runtime errors
26+
27+
???+ error "ModuleNotFoundError or ImportError"
28+
**Symptoms:**
29+
- `ModuleNotFoundError: No module named 'aws_lambda_powertools'`
30+
- Function fails at runtime with import errors
31+
32+
**Solutions:**
33+
```bash
34+
--8<-- "examples/build_recipes/troubleshooting/debug-import-errors.sh"
35+
```
36+
37+
???+ error "Architecture mismatch errors"
38+
**Symptoms:**
39+
- `ImportError: /lib64/libc.so.6: version GLIBC_2.XX not found`
40+
- Compiled extensions fail to load
41+
42+
**Solutions:**
43+
```bash
44+
--8<-- "examples/build_recipes/troubleshooting/fix-architecture-mismatch.sh"
45+
```
46+
47+
### Performance issues
48+
49+
???+ warning "Slow cold starts"
50+
**Symptoms:**
51+
- High initialization duration in CloudWatch logs
52+
- Timeouts on first invocation
53+
54+
**Solutions:**
55+
```bash
56+
--8<-- "examples/build_recipes/troubleshooting/optimize-cold-starts.sh"
57+
```
58+
59+
### Build and deployment issues
60+
61+
???+ error "Build inconsistencies across environments"
62+
**Symptoms:**
63+
- Works locally but fails in CI/CD
64+
- Different behavior between team members
65+
66+
**Solutions:**
67+
```bash
68+
--8<-- "examples/build_recipes/troubleshooting/fix-build-inconsistencies.sh"
69+
```
70+
71+
???+ error "Layer compatibility issues"
72+
**Symptoms:**
73+
- Layer not found or incompatible runtime
74+
- Version conflicts between layer and function dependencies
75+
76+
**Solutions:**
77+
```bash
78+
--8<-- "examples/build_recipes/troubleshooting/fix-layer-compatibility.sh"
79+
```
Collapse file

‎examples/build_recipes/troubleshooting/debug-import-errors.sh‎

Copy file name to clipboard
+12Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/bin/bash
2+
# 1. Verify dependencies are in the package
3+
unzip -l lambda-package.zip | grep powertools
4+
5+
# 2. Check Python path in Lambda
6+
python -c "import sys; print(sys.path)"
7+
8+
# 3. Ensure platform compatibility
9+
pip install --platform manylinux2014_x86_64 --only-binary=:all: aws-lambda-powertools[all]
10+
11+
# 4. Test imports locally
12+
cd build && python -c "from aws_lambda_powertools import Logger; print('OK')"
Collapse file

‎examples/build_recipes/troubleshooting/fix-architecture-mismatch.sh‎

Copy file name to clipboard
+8Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#!/bin/bash
2+
# Use Docker with Lambda base image
3+
docker run --rm -v "$PWD":/var/task public.ecr.aws/lambda/python:3.13 \
4+
pip install aws-lambda-powertools[all] -t /var/task/
5+
6+
# Or force Linux-compatible wheels
7+
pip install --platform manylinux2014_x86_64 --implementation cp \
8+
--python-version 3.13 --only-binary=:all: aws-lambda-powertools[all]
Collapse file

‎examples/build_recipes/troubleshooting/fix-build-inconsistencies.sh‎

Copy file name to clipboard
+18Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/bin/bash
2+
# 1. Use lock files for reproducible builds
3+
# Poetry: poetry.lock
4+
# uv: uv.lock
5+
# pip: requirements.txt with pinned versions
6+
7+
# 2. Use Docker for consistent build environment
8+
docker run --rm -v "$PWD":/app -w /app python:3.13-slim \
9+
bash -c "pip install -r requirements.txt -t build/"
10+
11+
# 3. Pin all tool versions
12+
pip==24.0
13+
poetry==1.8.0
14+
uv==0.1.0
15+
16+
# 4. Use same Python version everywhere
17+
python-version: '3.13' # In CI/CD
18+
python = "^3.13" # In pyproject.toml
Collapse file

‎examples/build_recipes/troubleshooting/fix-layer-compatibility.sh‎

Copy file name to clipboard
+13Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/bin/bash
2+
# 1. Use correct layer ARN for your region and Python version
3+
# Check: https://docs.powertools.aws.dev/lambda/python/latest/#lambda-layer
4+
5+
# 2. Verify layer compatibility
6+
aws lambda get-layer-version \
7+
--layer-name AWSLambdaPowertoolsPythonV3-python313-x86_64 \
8+
--version-number 22 \
9+
--region-name {REGION}
10+
11+
# 3. Avoid version conflicts
12+
# Don't include Powertools for AWS in deployment package if using layer
13+
pip install pydantic requests -t build/ # Exclude powertools
Collapse file

‎examples/build_recipes/troubleshooting/optimize-cold-starts.sh‎

Copy file name to clipboard
+14Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/bin/bash
2+
# 1. Optimize package size (see above)
3+
4+
# 2. Use public Powertools for AWS layer
5+
# Layer ARN: arn:aws:lambda:{REGION}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:1
6+
7+
# 3. Enable provisioned concurrency for critical functions
8+
aws lambda put-provisioned-concurrency-config \
9+
--function-name my-function \
10+
--provisioned-concurrency-config ProvisionedConcurrencyCount=10 \
11+
--region-name {REGION}
12+
13+
# 4. Minimize imports in handler
14+
# Import only what you need, avoid heavy imports at module level
Collapse file

‎examples/build_recipes/troubleshooting/optimize-package-size.sh‎

Copy file name to clipboard
+14Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/bin/bash
2+
# 1. Use Lambda Layers for heavy dependencies
3+
pip install aws-lambda-powertools[all] -t layers/powertools/python/
4+
5+
# 2. Remove unnecessary files
6+
find build/ -name "*.pyc" -delete
7+
find build/ -name "__pycache__" -type d -exec rm -rf {} +
8+
find build/ -name "tests" -type d -exec rm -rf {} +
9+
10+
# 3. Strip debug symbols from compiled libraries
11+
find build/ -name "*.so" -exec strip --strip-debug {} \;
12+
13+
# 4. Use container images for very large packages
14+
# Deploy as container image instead of ZIP
Collapse file

‎mkdocs.yml‎

Copy file name to clipboardExpand all lines: mkdocs.yml
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ nav:
4242
- build_recipes/index.md
4343
- Getting started: build_recipes/getting-started.md
4444
- CI/CD integration: build_recipes/cicd-integration.md
45+
- Troubleshooting: build_recipes/troubleshooting.md
4546
- Upgrade guide: upgrade.md
4647
- We Made This (Community): we_made_this.md
4748
- Roadmap: roadmap.md
@@ -242,6 +243,7 @@ plugins:
242243
- build_recipes/index.md
243244
- build_recipes/getting-started.md
244245
- build_recipes/cicd-integration.md
246+
- build_recipes/troubleshooting.md
245247

246248
- mkdocstrings:
247249
default_handler: python

0 commit comments

Comments
0 (0)
You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.