Cloudflare Troubleshooting

Cloudflare Troubleshooting

Methodology base: the general evidence-driven network-diagnosis discipline (falsification, layered isolation, counter-review) lives in the debugging-network-issues skill. This skill is the Cloudflare domain layer on top of it.

Core Principle

Investigate with evidence, not assumptions. Always query Cloudflare API to examine actual configuration before diagnosing issues. The skill's value is the systematic investigation methodology, not predetermined solutions.

Investigation Methodology

1. Gather Credentials

Reuse the domain and authorized Cloudflare connection already supplied by the user or project configuration. Ask only for missing connection information: domain, account email plus Global API Key, or API Token. Keep the working authentication method; troubleshooting does not require replacing it.

Global API Key location: Cloudflare Dashboard → My Profile → API Tokens → View Global API Key

2. Get Zone Information

First step for any Cloudflare troubleshooting - obtain the zone ID:

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

Select the exact matching zone and account before extracting its id; do not blindly select the first result when account or domain identity is ambiguous. Use that zone’s account.id for account-scoped calls.

3. Investigate Systematically

For each issue, gather evidence before making conclusions. Use Cloudflare API to inspect:

• Current configuration state
• Recent changes (if audit log available)
• Related settings that might interact

Common Investigation Patterns

Redirect Loops (ERR_TOO_MANY_REDIRECTS)

Evidence gathering sequence:

1. Check SSL/TLS mode:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

   Look for: result.value - tells current SSL mode

2. Check Always Use HTTPS setting:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/always_use_https" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

3. Check Page Rules for redirects:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/pagerules" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

   Look for: forwarding_url or always_use_https actions

4. Test origin server directly (if possible):

   curl -I -H "Host: <domain>" https://<origin_ip>

Diagnosis logic:

• SSL mode "flexible" + origin enforces HTTPS = redirect loop
• Multiple redirect rules can conflict
• Check browser vs curl behavior differences

Fix:

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings/ssl" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key" \
  -H "Content-Type: application/json" \
  --data '{"value":"full"}'

Purge cache after fix:

curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key" \
  -d '{"purge_everything":true}'

Email Routing and Forwarding

For alias delivery, destination verification, catch-all behavior or forwarding MX issues, follow Email Routing. It supplies the account/zone API read sequence and separates saved configuration from actual Inbox arrival.

DNS Issues

Evidence gathering:

1. List DNS records:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

2. Check external DNS resolution:

   dig <domain>
   dig @8.8.8.8 <domain>

3. Check DNSSEC status:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dnssec" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

Look for:

• Missing A/AAAA/CNAME records
• Incorrect proxy status (proxied vs DNS-only)
• TTL values
• Conflicting records

SSL Certificate Errors

Evidence gathering:

1. Check SSL certificate status:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/ssl/certificate_packs" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

2. Check origin certificate (if using Full Strict):

   openssl s_client -connect <origin_ip>:443 -servername <domain>

3. Check SSL settings:

   • Minimum TLS version
   • TLS 1.3 status
   • Opportunistic Encryption

Common issues:

• Error 526: SSL mode is "strict" but origin cert invalid
• Error 525: SSL handshake failure at origin
• Provisioning delay: Wait 15-30 minutes for Universal SSL

Origin Server Errors (502/503/504)

Evidence gathering:

1. Check if origin is reachable:

   curl -I -H "Host: <domain>" https://<origin_ip>

2. Check DNS records point to correct origin:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

3. Review load balancer config (if applicable):

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/load_balancers" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"

4. Check firewall rules:

   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/firewall/rules" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"