Cloudfront Diagnostics

CloudFront Diagnostics

When to use

Any CloudFront investigation where the console alone is insufficient — cache behavior analysis, origin troubleshooting, SSL/TLS debugging, edge function errors, performance optimization, security configuration, or routing issues.

Investigation workflow

Step 1 — Collect and triage

aws cloudfront get-distribution --id 
aws cloudfront get-distribution-config --id 
aws cloudfront list-distributions --query 'DistributionList.Items[*].{Id:Id,Domain:DomainName,Status:Status}'
aws cloudwatch get-metric-statistics --namespace AWS/CloudFront --metric-name Requests --dimensions Name=DistributionId,Value= Name=Region,Value=Global --start-time  --end-time  --period 300 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/CloudFront --metric-name 4xxErrorRate --dimensions Name=DistributionId,Value= Name=Region,Value=Global --start-time  --end-time  --period 300 --statistics Average
aws cloudwatch get-metric-statistics --namespace AWS/CloudFront --metric-name 5xxErrorRate --dimensions Name=DistributionId,Value= Name=Region,Value=Global --start-time  --end-time  --period 300 --statistics Average

Step 2 — Domain deep dive

aws cloudfront get-distribution-config --id  --query 'DistributionConfig.CacheBehaviors'
aws cloudfront get-distribution-config --id  --query 'DistributionConfig.Origins'
aws cloudfront list-invalidations --distribution-id 
aws cloudfront get-invalidation --distribution-id  --id 
aws acm describe-certificate --certificate-arn  --region us-east-1
aws cloudfront list-cloud-front-origin-access-identities
aws cloudfront list-origin-access-controls

Step 3 — Detailed investigation

aws cloudfront get-cache-policy --id 
aws cloudfront get-origin-request-policy --id 
aws cloudfront get-response-headers-policy --id 
aws lambda get-function --function-name  --qualifier 
aws cloudfront describe-function --name 
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=cloudfront.amazonaws.com
aws cloudfront get-realtime-log-config --name 

Read references/cloudfront-guardrails.md before concluding on any CloudFront issue.

Tool quick reference

| Tool / API | When to use | |------------|-------------| | get-distribution | Full distribution details | | get-distribution-config | Distribution configuration | | list-invalidations | Check invalidation status | | get-cache-policy | Cache key and TTL settings | | get-origin-request-policy | Headers/cookies/query strings forwarded to origin | | get-response-headers-policy | Security headers, CORS | | list-origin-access-controls | OAC configuration for S3 | | describe-function | CloudFront Functions details | | acm describe-certificate | SSL/TLS certificate status | | get-realtime-log-config | Real-time log configuration | | get-monitoring-subscription | Additional metrics | | list-functions | List CloudFront Functions |

Gotchas: CloudFront

• Cache behavior precedence: behaviors are evaluated in order by path pattern. The first match wins. The default (*) behavior is always last. Longest match does NOT win — order matters.
• Origin failover: only triggers on 5xx errors from the origin or connection failures. 4xx errors do NOT trigger failover. Configure an origin group with primary and secondary origins.
• TTL hierarchy: Cache-Control/Expires headers from the origin take precedence over CloudFront cache policy TTL settings, UNLESS the cache policy minimum TTL is greater than the origin header value. Order: max(MinTTL, min(MaxTTL, origin-header-or-DefaultTTL)).
• Invalidation costs: first 1,000 invalidation paths per month are free. After that, $0.005 per path. Invalidations are NOT instant — they propagate to all edge locations and typically take 1-2 minutes but can take up to 10-15 minutes. Use versioned file names instead when possible.
• OAC vs OAI: Origin Access Control (OAC) is the recommended method for S3 origins. OAI (Origin Access Identity) is legacy. OAC supports SSE-KMS, all S3 regions, and S3 Object Lambda. OAI does not support SSE-KMS or newer S3 features.
• Lambda@Edge limits: viewer request/response functions have 5-second timeout and 128 MB memory. Origin request/response functions have 30-second timeout and 10 GB memory (configurable). Functions must be in us-east-1. No environment variables, no VPC, no layers, no ARM.
• CloudFront Functions limits: 10 ms execution time, 2 MB max function size, 10 KB max response body for viewer response events. No network access, no file system access. Only viewer request and viewer response events.
• Custom error pages: cached separately with their own TTL (Error Caching Minimum TTL). Changing the error page requires invalidation of the error response. Can map HTTP error codes to different response codes.
• Geo-restriction: uses a third-party GeoIP database. Not 100% accurate. Applies to the entire distribution, not per behavior. Use signed URLs/cookies or Lambda@Edge for per-path geo-restriction.
• Signed URLs vs signed cookies: signed URLs are for individual files. Signed cookies are for multiple files (e.g., HLS video segments). Both use CloudFront key pairs or trusted key groups. Key pairs are legacy — use trusted key groups.
• Field-level encryption: encrypts specific POST body fields at the edge. Uses RSA encryption with a public key. Only the application with the private key can decrypt. Limited to 10 fields and 1 MB total POST body.
• HTTP/2 is enabled by default. HTTP/3 (QUIC) must be explicitly enabled. Both only apply to viewer-to-CloudFront connections. CloudFront-to-origin always uses HTTP/1.1.
• WebSocket support: requires the distribution to allow GET and HEAD methods (minimum). WebSocket connections upgrade from HTTP. The origin must support WebSocket. Idle timeout is 10 minutes.
• Origin Shield: adds an additional caching layer between edge locations and the origin. Reduces origin load. Choose the Origin Shield region closest to your origin. Adds per-request cost.

Anti-hallucination rules

1. Always cite specific distribution configurations, cache policies, or API responses as evidence.
2. Cache behavior order matters — first match wins, NOT longest match. Never claim longest-match behavior.
3. Invalidations are NOT instant. Never claim content is immediately updated after invalidation.
4. OAI is legacy. Never recommend OAI for new distributions — always recommend OAC.
5. Lambda@Edge functions MUST be in us-east-1. Never suggest deploying them in other regions.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

30 runbooks

| Category | IDs | Covers | |----------|-----|--------| | A — Cache | A1-A4 | Cache miss, stale content, invalidation failures, cache key issues | | B — Origin | B1-B4 | Origin connection failures, S3 origin issues, custom origin errors, origin failover | | C — SSL/TLS | C1-C3 | Certificate errors, SNI issues, origin SSL | | D — Performance | D1-D3 | High latency, bandwidth throttling, compression | | E — Security | E1-E3 | Signed URL/cookie issues, geo-restriction, field-level encryption | | F — Edge Functions | F1-F3 | Lambda@Edge errors, CloudFront Functions, function association | | G — Errors | G1-G3 | 4xx errors, 5xx errors, custom error responses | | H — Routing | H1-H2 | Behavior matching, redirect loops | | I — Logging | I1-I2 | Access logs, real-time logs | | Z — Catch-All | Z1 | General troubleshooting |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aws-samples
• Source: aws-samples/sample-ai-agent-skills
• License: MIT-0

Install and usage instructions live in the source repository linked above.