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 <distribution-id>
aws cloudfront get-distribution-config --id <distribution-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=<distribution-id> Name=Region,Value=Global --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/CloudFront --metric-name 4xxErrorRate --dimensions Name=DistributionId,Value=<distribution-id> Name=Region,Value=Global --start-time <start> --end-time <end> --period 300 --statistics Average
aws cloudwatch get-metric-statistics --namespace AWS/CloudFront --metric-name 5xxErrorRate --dimensions Name=DistributionId,Value=<distribution-id> Name=Region,Value=Global --start-time <start> --end-time <end> --period 300 --statistics Average

Step 2 — Domain deep dive

aws cloudfront get-distribution-config --id <distribution-id> --query 'DistributionConfig.CacheBehaviors'
aws cloudfront get-distribution-config --id <distribution-id> --query 'DistributionConfig.Origins'
aws cloudfront list-invalidations --distribution-id <distribution-id>
aws cloudfront get-invalidation --distribution-id <distribution-id> --id <invalidation-id>
aws acm describe-certificate --certificate-arn <cert-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 <cache-policy-id>
aws cloudfront get-origin-request-policy --id <origin-request-policy-id>
aws cloudfront get-response-headers-policy --id <response-headers-policy-id>
aws lambda get-function --function-name <function-name> --qualifier <version>
aws cloudfront describe-function --name <function-name>
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=cloudfront.amazonaws.com
aws cloudfront get-realtime-log-config --name <config-name>

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

Tool quick reference

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