# Edge Functions Diagnostics

> 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.

- Skill: `aws-samples/edge-functions-diagnostics` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add aws-samples/edge-functions-diagnostics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/edge-functions-diagnostics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aws-samples/edge-functions-diagnostics

---


# 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

1. Always cite specific function names, distribution IDs, or CloudWatch metrics as evidence.
2. CloudFront Functions and Lambda@Edge have different capabilities and limits. Never conflate them.
3. Lambda@Edge MUST be in us-east-1. Never suggest deploying in other regions.
4. CloudFront Functions have a 1ms limit. Never suggest complex processing in CloudFront Functions.
5. 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 |