Edge Functions Diagnostics (CloudFront Functions & Lambda@Edge)
When to use
Any CloudFront Functions or Lambda@Edge investigation — function creation, publishing, deployment, replication, viewer/origin request/response errors, timeouts, memory limits, testing, logging, or cache behavior association.
Investigation workflow
Step 1 — Collect and triage
aws cloudfront list-functions --query 'FunctionList.Items[*].{Name:Name,Status:Status,Stage:FunctionConfig.Runtime}'
aws cloudfront list-distributions --query 'DistributionList.Items[*].{Id:Id,Status:Status,DomainName:DomainName}'
aws lambda list-functions --query 'Functions[?starts_with(FunctionName, `us-east-1.`)]'
Step 2 — Domain deep dive
aws cloudfront describe-function --name <function-name> --stage LIVE
aws cloudfront get-distribution-config --id <distribution-id>
aws lambda get-function --function-name <function-name> --qualifier <version>
Step 3 — Detailed investigation
aws cloudwatch get-metric-statistics --namespace AWS/CloudFront --metric-name FunctionExecutionErrors --dimensions Name=DistributionId,Value=<dist-id>,Name=FunctionName,Value=<func-name> --start-time <start> --end-time <end> --period 300 --statistics Sum
aws logs filter-log-events --log-group-name /aws/cloudfront/function/<function-name> --start-time <epoch-ms> --filter-pattern "ERROR"
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=cloudfront.amazonaws.com --max-results 20
Read references/guardrails.md before concluding on any edge function issue.
Tool quick reference
| Tool / API |
When to use |
cloudfront list-functions |
List CloudFront Functions |
cloudfront describe-function |
Get function details and metadata |
cloudfront test-function |
Test function with a test event |
cloudfront get-distribution-config |
Get distribution and cache behavior config |
lambda get-function |
Get Lambda@Edge function details |
cloudwatch get-metric-statistics |
Check function execution metrics |
logs filter-log-events |
Search function execution logs |
Gotchas: Edge Functions
- CloudFront Functions run in the viewer-facing edge (viewer-request, viewer-response only). Lambda@Edge runs in regional edge caches (all four event types).
- CloudFront Functions have a 1ms execution time limit and 2MB max package size. Lambda@Edge has 5s (viewer) / 30s (origin) timeout and 1MB/50MB package limits.
- CloudFront Functions use JavaScript (ECMAScript 5.1 compatible runtime). Lambda@Edge supports Node.js and Python.
- Lambda@Edge functions MUST be deployed in us-east-1. They are replicated to edge locations automatically.
- Lambda@Edge functions cannot use environment variables, layers, VPC, DLQ, or provisioned concurrency.
- CloudFront Functions cannot make network calls. Lambda@Edge can make network calls in origin events.
- Function associations are per cache behavior, not per distribution. Different paths can use different functions.
Anti-hallucination rules
- Always cite specific function names, distribution IDs, or CloudWatch metrics as evidence.
- CloudFront Functions and Lambda@Edge have different capabilities and limits. Never conflate them.
- Lambda@Edge MUST be in us-east-1. Never suggest deploying in other regions.
- CloudFront Functions have a 1ms limit. Never suggest complex processing in CloudFront Functions.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
14 runbooks
| Category |
IDs |
Covers |
| A — CloudFront Functions |
A1-A2 |
Function creation, publish errors |
| B — Lambda@Edge Deployment |
B1-B2 |
Deployment, replication |
| C — Viewer Events |
C1-C2 |
Viewer request errors, viewer response errors |
| D — Origin Events |
D1-D2 |
Origin request errors, origin response errors |
| E — Resource Limits |
E1-E2 |
Function timeout, memory limits |
| F — Development |
F1-F2 |
Testing failures, logging issues |
| G — Association |
G1 |
Cache behavior association |
| Z — Catch-All |
Z1 |
General troubleshooting |
1---2name: edge-functions-diagnostics3description: Use this skill to investigate and troubleshoot CloudFront Functions and Lambda@Edge problems by analyzing function creation, deployment, replication, viewer/origin request/response errors, timeouts, memory limits, testing, logging, cache behavior association, and following structured runbooks. Activate when: CloudFront Function creation failures, publish errors, Lambda@Edge deployment issues, replication delays, viewer/origin event errors, timeout or memory issues, testing failures, logging problems, cache behavior association errors, or the user says something is wrong with edge functions.4---56# Edge Functions Diagnostics (CloudFront Functions & Lambda@Edge)78## When to use910Any CloudFront Functions or Lambda@Edge investigation — function creation, publishing, deployment, replication, viewer/origin request/response errors, timeouts, memory limits, testing, logging, or cache behavior association.1112## Investigation workflow1314### Step 1 — Collect and triage1516```17aws cloudfront list-functions --query 'FunctionList.Items[*].{Name:Name,Status:Status,Stage:FunctionConfig.Runtime}'18aws cloudfront list-distributions --query 'DistributionList.Items[*].{Id:Id,Status:Status,DomainName:DomainName}'19aws lambda list-functions --query 'Functions[?starts_with(FunctionName, `us-east-1.`)]'20```2122### Step 2 — Domain deep dive2324```25aws cloudfront describe-function --name <function-name> --stage LIVE26aws cloudfront get-distribution-config --id <distribution-id>27aws lambda get-function --function-name <function-name> --qualifier <version>28```2930### Step 3 — Detailed investigation3132```33aws cloudwatch get-metric-statistics --namespace AWS/CloudFront --metric-name FunctionExecutionErrors --dimensions Name=DistributionId,Value=<dist-id>,Name=FunctionName,Value=<func-name> --start-time <start> --end-time <end> --period 300 --statistics Sum34aws logs filter-log-events --log-group-name /aws/cloudfront/function/<function-name> --start-time <epoch-ms> --filter-pattern "ERROR"35aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=cloudfront.amazonaws.com --max-results 2036```3738Read `references/guardrails.md` before concluding on any edge function issue.3940## Tool quick reference4142| Tool / API | When to use |43|------------|-------------|44| `cloudfront list-functions` | List CloudFront Functions |45| `cloudfront describe-function` | Get function details and metadata |46| `cloudfront test-function` | Test function with a test event |47| `cloudfront get-distribution-config` | Get distribution and cache behavior config |48| `lambda get-function` | Get Lambda@Edge function details |49| `cloudwatch get-metric-statistics` | Check function execution metrics |50| `logs filter-log-events` | Search function execution logs |5152## Gotchas: Edge Functions5354- CloudFront Functions run in the viewer-facing edge (viewer-request, viewer-response only). Lambda@Edge runs in regional edge caches (all four event types).55- CloudFront Functions have a 1ms execution time limit and 2MB max package size. Lambda@Edge has 5s (viewer) / 30s (origin) timeout and 1MB/50MB package limits.56- CloudFront Functions use JavaScript (ECMAScript 5.1 compatible runtime). Lambda@Edge supports Node.js and Python.57- Lambda@Edge functions MUST be deployed in us-east-1. They are replicated to edge locations automatically.58- Lambda@Edge functions cannot use environment variables, layers, VPC, DLQ, or provisioned concurrency.59- CloudFront Functions cannot make network calls. Lambda@Edge can make network calls in origin events.60- Function associations are per cache behavior, not per distribution. Different paths can use different functions.6162## Anti-hallucination rules63641. Always cite specific function names, distribution IDs, or CloudWatch metrics as evidence.652. CloudFront Functions and Lambda@Edge have different capabilities and limits. Never conflate them.663. Lambda@Edge MUST be in us-east-1. Never suggest deploying in other regions.674. CloudFront Functions have a 1ms limit. Never suggest complex processing in CloudFront Functions.685. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.6970## 14 runbooks7172| Category | IDs | Covers |73|----------|-----|--------|74| A — CloudFront Functions | A1-A2 | Function creation, publish errors |75| B — Lambda@Edge Deployment | B1-B2 | Deployment, replication |76| C — Viewer Events | C1-C2 | Viewer request errors, viewer response errors |77| D — Origin Events | D1-D2 | Origin request errors, origin response errors |78| E — Resource Limits | E1-E2 | Function timeout, memory limits |79| F — Development | F1-F2 | Testing failures, logging issues |80| G — Association | G1 | Cache behavior association |81| Z — Catch-All | Z1 | General troubleshooting |
aws-samples