cloudflare-troubleshooting

intent

troubleshoot cloudflare misconfigurations by querying the cloudflare api to gather evidence before diagnosing or fixing issues. use this skill when your site shows redirect loops (err_too_many_redirects), ssl/tls errors, dns resolution failures, 502/503/504 origin errors, or other cloudflare-related problems. the core value is systematic investigation methodology that identifies root causes through api inspection of actual configuration state, not guesswork or trial-and-error fixes.

inputs

required credentials and access:

• domain name (the site you're troubleshooting)
• cloudflare account email address
• cloudflare global api key or api token (retrieve from cloudflare dashboard > my profile > api tokens > view global api key)
• optional: cloudflare api token with zone:read and zone:edit scopes (more secure than global api key; see decision points)

external connections:

• cloudflare api v4 (https://api.cloudflare.com/client/v4/) - rest api for querying zones, dns records, settings, ssl certificates, firewall rules, load balancers
• optional external tools: curl, dig/nslookup for external dns verification, openssl for certificate inspection

edge case context:

• api rate limits (cloudflare allows 1200 requests per 5 minutes for most endpoints; higher for some, lower for others)
• auth token expiry (api tokens can expire; global api keys do not)
• network connectivity to cloudflare api and origin server

procedure

1. gather and validate credentials

   • input: request from user the domain name, cloudflare account email, and api key/token
   • output: confirmed credentials stored securely (never logged or output to user)
   • note: test credentials immediately by attempting a zones list call to catch auth failures early

2. retrieve zone id for the domain

   • input: domain name, email, api key
   • execute: curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=<domain>" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[0].id'
   • output: zone_id (alphanumeric string, ~32 chars)
   • validation: check that success field is true and result array is not empty; if empty, domain is not in cloudflare account

3. diagnose issue type by gathering evidence

   • input: zone_id, symptom description from user (e.g., err_too_many_redirects, ssl certificate error, dns not resolving, 502/503/504)
   • execute: based on issue type, run one or more of the targeted investigation sequences below (steps 3a-3e)
   • output: raw api responses and external test results

4. step 3a: redirect loop investigation (err_too_many_redirects)

   • input: zone_id, email, api_key
   • execute in sequence:
     • check ssl/tls mode: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result.value'
     • check always_use_https setting: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/always_use_https" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result.value'
     • check page rules: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/pagerules" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[] | select(.actions[].id == "forwarding_url" or .actions[].id == "always_use_https")'
     • external test: curl -I -H "Host: <domain>" https://<origin_ip> (if origin ip known)
   • output: ssl mode value, always_use_https value, list of active page rules with redirect actions, origin server response headers
   • edge case: if page rules exceed 20 items, result set may be paginated; use jq to extract forwarding_url and always_use_https actions only

5. step 3b: dns issue investigation

   • input: zone_id, email, api_key, domain
   • execute in sequence:
     • list dns records: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[] | {name, type, content, proxied, ttl}'
     • external resolution test: dig <domain> +short and dig @8.8.8.8 <domain> +short
     • check dnssec status: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dnssec" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result.status'
   • output: table of dns records (name, type, ip/content, proxied status, ttl), external resolution results from public dns, dnssec status (enabled/disabled/pending)
   • edge case: if dns_records result exceeds 500 items, paginate using per_page and page params; prioritize checking root (@) and www records first

6. step 3c: ssl certificate error investigation (err_525, err_526, ssl_handshake_failure)

   • input: zone_id, email, api_key, origin_ip, domain
   • execute in sequence:
     • check ssl certificate packs: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/ssl/certificate_packs" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[] | {id, type, hosts, status}'
     • check ssl settings: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result' and curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/min_tls_version" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result.value'
     • external origin cert check: openssl s_client -connect <origin_ip>:443 -servername <domain> -showcerts 2>/dev/null | openssl x509 -noout -dates -subject
   • output: certificate pack status (active, pending, deleted), ssl mode, min tls version, origin certificate validity dates and subject
   • edge case: universal ssl provisioning takes 15-30 minutes; if status is pending_validation, wait and retry; err_526 indicates ssl mode is full_strict but origin cert is invalid or expired

7. step 3d: origin server error investigation (502, 503, 504)

   • input: zone_id, email, api_key, origin_ip, domain
   • execute in sequence:
     • verify origin reachability: curl -I -H "Host: <domain>" https://<origin_ip>
     • check dns records point to correct origin: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records?type=A,AAAA,CNAME" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[] | {name, type, content}'
     • check load balancer config: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/load_balancers" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[] | {id, name, default_pools, description}'
     • check firewall rules: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/firewall/rules?limit=100" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[] | {id, description, action, filter}'
   • output: origin server http status and headers, dns record targets, active load balancers and default pools, firewall rules that may block requests
   • edge case: if origin is unreachable (connection timeout or refused), origin may be down; ask user to verify origin health outside cloudflare; firewall rule result set may exceed 100; paginate to check all rules

8. step 3e: investigate unfamiliar issues using cloudflare api reference

   • input: issue description, zone_id, email, api_key
   • execute: browse https://developers.cloudflare.com/api/ to find relevant endpoint; start with a GET call to understand data structure before making changes
   • example: curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" | jq '.result[] | {id, value}' lists all available zone settings
   • output: api response schema and available settings/endpoints for further investigation

9. analyze evidence and determine root cause

   • input: all evidence gathered from steps 3a-3e
   • output: root cause hypothesis with supporting api data (e.g., "ssl mode is flexible but origin enforces https, causing redirect loop")
   • cross-reference related settings: settings often interact (e.g., always_use_https + ssl mode flexible + origin https = loop)

10. apply targeted fix via api

    • input: root cause identified, zone_id, email, api_key
    • execute: based on root cause, use appropriate http method:
      • patch: update existing setting (e.g., ssl mode, always_use_https, ttl)
      • post: create resource or trigger action (e.g., purge cache, create dns record)
      • delete: remove resource (e.g., delete page rule, delete dns record)
    • example fix for redirect loop: curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" -H "Content-Type: application/json" --data '{"value":"full"}'
    • output: api response with success field (true/false) and any error messages

11. purge cache if configuration changed

    • input: zone_id, email, api_key, whether configuration change affects content delivery (ssl/redirect/dns changes usually do)
    • execute: curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" -H "X-Auth-Email: <email>" -H "X-Auth-Key: <api_key>" -H "Content-Type: application/json" -d '{"purge_everything":true}'
    • output: purge request acceptance; note that purge takes 30-60 seconds to propagate across edge servers
    • edge case: avoid running purge_cache more than once per minute per zone to respect rate limits

12. verify fix with follow-up api query and external test

    • input: zone_id, email, api_key, domain, original issue symptom
    • execute: re-run the same api query from step 3 that revealed the problem (e.g., check ssl mode again, re-test dns resolution with dig, curl origin again)
    • output: confirmation that setting has changed and issue symptom no longer appears
    • external verification: curl site via domain, check dns resolution with dig, test ssl cert with openssl, browse site in incognito window to bypass browser cache

13. communicate resolution and propagation wait times to user

    • input: fix applied and verified
    • output: user notification with:
      • root cause explanation (non-technical summary acceptable)
      • fix applied and verification status
      • wait time expectations: edge server propagation 30-60 seconds, dns propagation up to 48 hours, browser cache clear needed manually
      • any follow-up actions user must take (e.g., clear browser cache, wait for dns propagation, restart origin service)

decision points

if user provides global api key vs scoped api token:

• global api key: proceed with all steps (has full account permissions, but less secure)
• api token with scoped permissions: proceed with read-only investigation steps (steps 2-3); for fix steps (10-11), check token scopes; if token lacks zone:edit, inform user that fix requires elevated token or global key

if zone lookup returns empty result set (domain not in cloudflare account):

• do not proceed with investigation
• inform user: domain is not added to cloudflare account or is registered under different account; user must verify domain ownership in cloudflare dashboard first

if auth fails (401/403 response):

• do not proceed; api key/email incorrect or token expired
• ask user to re-verify credentials and regenerate api token if expired

if api rate limit reached (http 429):

• pause for 60 seconds and retry request
• if limit exceeded repeatedly, reduce investigation scope (skip optional queries like load balancer check if not relevant to issue)

if ssl certificate pack status is pending_validation (ssl errors):

• do not apply ssl mode full_strict yet
• inform user: universal ssl certificate is provisioning; wait 15-30 minutes, then retry
• re-query certificate_packs after wait

if origin server is unreachable (curl connection timeout, refused, or no response):

• do not assume cloudflare misconfiguration
• inform user: origin server is down or not accepting connections from cloudflare ips; verify origin health outside cloudflare first (direct access, health checks, logs)

if multiple page rules with redirect actions exist:

• do not apply fix blindly
• inform user: multiple conflicting redirect rules detected; ask which rules are intentional before removing/modifying

if dns records show mixed proxied/dns-only status on a single subdomain:

• do not assume dns is broken
• investigate: ask user which status is intentional; mixed status can be correct (e.g., separate a record for mail server as dns-only)

if browser test shows different behavior than curl test:

• likely browser cache or cookie issue, not cloudflare misconfiguration
• advise user to test in incognito window or clear browser cache; curl result is authoritative for cloudflare state

output contract

investigation evidence output:

• raw api responses as json (use jq to extract relevant fields: value, type, content, status, etc.)
• external test results (dig output, curl headers, openssl cert dates)
• structured table or list format for multi-item results (dns records, page rules, firewall rules)

fix confirmation output:

• api patch/post response with success: true and affected resource id
• re-query result showing new setting value matches intended fix
• purge_cache acceptance confirmation (success: true)

final output to user:

• one-line root cause summary (non-technical language acceptable)
• step-by-step investigation evidence that led to diagnosis (reproducible by user)
• fix applied and verification status
• propagation timeline (when user will see effect)
• any follow-up actions user must take

output location:

• all api responses and test results included inline in skill output (do not store in files unless user explicitly asks)
• no api keys or credentials logged or output to user

outcome signal

the skill has worked when:

1. investigation phase complete: user can see exactly which api endpoints were queried, what data was returned, and which setting or configuration is causing the issue (evidence-based, not guesswork)

2. fix applied and verified: api response confirms setting has changed (e.g., ssl mode changed from flexible to full), and re-query of same endpoint shows new value in effect

3. external verification successful: follow-up curl/dig/openssl test shows issue symptom no longer present (no redirect loop, dns resolves correctly, ssl cert is valid, origin responds with 2xx)

4. user can reproduce investigation: user has api commands and results documented well enough to run same queries themselves later or with different tool

5. issue resolved within stated propagation timeline: user reports site now works as expected after waiting for edge propagation, dns propagation, or browser cache clear (whichever applies)

6. user understands root cause: user can articulate what was misconfigured and why fix resolved it, not just "skill fixed it"

credits: daymade (skills.sh)