# Cloudfront Diagnostics > Use this skill to investigate and troubleshoot Amazon CloudFront problems by analyzing distribution configurations, cache behaviors, origin settings, SSL/TLS certificates, edge functions, and following structured runbooks. Activate when: cache miss issues, stale content, invalidation failures, origin connection errors, S3 origin access problems, custom origin errors, SSL/TLS certificate issues, high latency, compression problems, signed URL/cookie failures, geo-restriction issues, Lambda@Edge errors, CloudFront Functions failures, 4xx/5xx errors, redirect loops, behavior matching issues, access log problems, or the user says something is wrong with CloudFront without naming specific symptoms. - Skill: `aws-samples/cloudfront-diagnostics` (Agent Skill, multi-file: 32 files) - Install (CLI): `npx skillmds@latest add aws-samples/cloudfront-diagnostics` - Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/cloudfront-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/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 |