Przejdź do treści
Biblioteka skilli
DevOps i chmura · Analiza

cloudflare-troubleshooting

/cloudflare-troubleshooting

Diagnozuje problemy z konfiguracją Cloudflare systematycznie przez API, w tym ERR_TOO_MANY_REDIRECTS, błędy SSL i problemy z DNS, na podstawie rzeczywistej konfiguracji.

Licencja
MIT
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
20
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/check_cloudflare_config.py, scripts/fix_ssl_mode.py

Co robi i kiedy

Diagnozuje problemy z konfiguracją Cloudflare systematycznie przez API, w tym ERR_TOO_MANY_REDIRECTS, błędy SSL i problemy z DNS, na podstawie rzeczywistej konfiguracji.

Oryginalny opis (EN)

Investigate and resolve Cloudflare configuration issues using API-driven evidence gathering. Use when troubleshooting ERR_TOO_MANY_REDIRECTS, SSL errors, DNS issues, or any Cloudflare-related problems. Focus on systematic investigation using Cloudflare API to examine actual configuration rather than making assumptions.

Jak działa

  1. Core Principle
  2. Investigation Methodology
  3. Common Investigation Patterns
  4. Learning New APIs
  5. API Reference Overview
  6. Best Practices
  7. Workflow Template
  8. Example: Complete Investigation
  9. When Scripts Are Useful
Sekcje z nagłówków SKILL.md, w oryginale · 327 linii, 1 491 słów
Podgląd SKILL.md
---
name: cloudflare-troubleshooting
description: Investigate and resolve Cloudflare configuration issues using API-driven evidence gathering. Use when troubleshooting ERR_TOO_MANY_REDIRECTS, SSL errors, DNS issues, or any Cloudflare-related problems. Focus on systematic investigation using Cloudflare API to examine actual configuration rather than making assumptions.
---

# 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

For zone-scoped troubleshooting, obtain the zone ID:

```bash
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.

For a Pages hostname that has never been attached, an empty exact-zone result is a finding, not an account ID or proof that the site is absent. Resolve the existing account/project from its authorized configuration and follow [Pages custom domains and DNSSEC migration](references/pages-custom-domain.md). Do not create a zone merely to make this lookup succeed.

### 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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   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):**
   ```bash
   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:**
```bash
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"}'
```

If stale HTTP redirects remain after the fix, purge the relevant HTTP cache:
```bash
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](references/email-routing.md). It supplies the account/zone API read sequence and separates saved configuration from actual Inbox arrival.

### DNS Issues

For a working `pages.dev` site with an unreachable custom hostname, missing Pages binding, or a nameserver/DNSSEC move, load [Pages custom domains and DNSSEC migration](references/pages-custom-domain.md) before changing DNS. It separates registrar identity, parent publication, recursive caches and normal-hostname acceptance.

**Evidence gathering:**

1. **List DNS records:**
   ```bash
   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:**
   ```bash
   dig <domain>
   dig @8.8.8.8 <domain>
   ```

3. **Check DNSSEC status:**
   ```bash
   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:**
   ```bash
   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):**
   ```bash
   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: inspect the selected product's certificate/domain validation state and report the remaining prerequisite or pending state

### Origin Server Errors (502/503/504)

**Evidence gathering:**

1. **Check if origin is reachable:**
   ```bash
   curl -I -H "Host: <domain>" https://<origin_ip>
   ```

2. **Check DNS records point to correct origin:**
   ```bash
   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):**
   ```bash
   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:**
   ```bash
   curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/firewall/rules" \
     -H "X-Auth-Email: email" \
     -H "X-Auth-Key: key"
   ```

## Learning New APIs

When encountering issues not covered above, consult Cloudflare API documentation:

1. **Browse API reference:** https://developers.cloudflare.com/api/
2. **Search for relevant endpoints** using issue keywords
3. **Check API schema** to understand available operations
4. **Test with GET requests** first to understand data structure
5. **Make changes with PATCH/POST** after confirming approach

**Pattern for exploring new APIs:**
```bash
# List available settings for a zone
curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings" \
  -H "X-Auth-Email: email" \
  -H "X-Auth-Key: key"
```

## API Reference Overview

Consult `references/api_overview.md` for:
- Common endpoints organized by category
- Request/response schemas
- Authentication patterns
- Rate limits and error handling

Consult `references/ssl_modes.md` for:
- Detailed SSL/TLS mode explanations
- Platform compatibility
- Security implications

Consult `references/common_issues.md` for:
- Issue patterns and symptoms
- Investigation checklists
- Platform-specific notes

## Best Practices

### Evidence-Based Investigation

1. **Query before assuming** - Use API to check actual state
2. **Gather multiple data points** - Cross-reference settings
3. **Check related configurations** - Settings often interact
4. **Verify externally** - Use dig/curl to confirm
5. **Test incrementally** - One change at a time

### API Usage

1. **Parse JSON responses** - Use `jq` or python for readability
2. **Check success field** - `"success": true/false` in responses
3. **Handle errors gracefully** - Read `errors` array in responses
4. **Respect rate limits** - Cloudflare API has limits
5. **Use appropriate methods:**
   - GET: Retrieve information
   - PATCH: Update settings
   - POST: Create resources / trigger actions
   - DELETE: Remove resources

### Making Changes

1. **Gather evidence first** - Understand current state
2. **Identify root cause** - Don't guess
3. **Apply targeted fix** - Change only what's needed
4. **Purge HTTP cache only when implicated** - A CDN purge does not publish registrar changes or clear recursive DNS caches
5. **Verify fix** - Re-query API to confirm
6. **Report the waiting stage and next observation:** use current activation state, registry publication policy and observed TTLs. Registrar save, parent publication and client recovery can occur at different times; do not prescribe a fixed delay or browser-cache clearing without evidence.

### Security

- Never log API keys in output
- Warn if user shares credentials in public context
- Recommend API Tokens with scoped permissions over Global API Key
- Use read-only operations for investigation

## Workflow Template

```
1. Reuse the configured domain and authorized API connection; obtain only missing values
2. Get zone_id via zones API
3. Investigate:
   - Query relevant APIs for evidence
   - Check multiple related settings
   - Verify with external tools (dig, curl)
4. Analyze evidence to determine root cause
5. Apply fix via appropriate API endpoint
6. Purge HTTP cache only if stale HTTP content is implicated
7. Verify fix via API query and normal-hostname external testing; provider or forced-IP success alone is partial
8. Inform user of resolution and any required actions
```

## Example: Complete Investigation

When user reports "site shows ERR_TOO_MANY_REDIRECTS":

```bash
# 1. Get zone ID
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" | jq '.result[] | select(.name == "example.com") | {id, account}'

# Select the intended account from the exact-domain result before using its id.
# 2. Check SSL mode (primary suspect for redirect loops)
curl -s -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" | jq '.result.value'

# If returns "flexible" and origin is GitHub Pages/Netlify/Vercel:

# 3. Fix by changing to "full"
curl -X PATCH "https://api.cloudflare.com/client/v4/zones/ZONE_ID/settings/ssl" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" \
  -H "Content-Type: application/json" \
  --data '{"value":"full"}'

# 4. Only if stale HTTP redirects remain, purge HTTP cache
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "X-Auth-Email: user@example.com" \
  -H "X-Auth-Key: abc123" \
  -d '{"purge_everything":true}'

# 5. Recheck the ordinary hostname and browser; report observed recovery or the unresolved layer
```

## When Scripts Are Useful

The bundled scripts (`scripts/check_cloudflare_config.py`, `scripts/fix_ssl_mode.py`) serve as:
- **Reference implementations** of investigation patterns
- **Quick diagnostic tools** when Python is available
- **Examples** of programmatic API usage

However, **prefer direct API calls via Bash/curl** for flexibility and transparency. Scripts should not limit capability - use them when convenient, but use raw API calls when needed for:
- Unfamiliar scenarios
- Edge cases
- Learning/debugging
- Operations not covered by scripts

The investigation methodology and API knowledge is the core skill, not the scripts.
Pliki w paczce (8)
  • SKILL.md 12 KB
  • references/api_overview.md 11 KB
  • references/common_issues.md 7 KB
  • references/email-routing.md 4 KB
  • references/pages-custom-domain.md 6 KB
  • references/ssl_modes.md 7 KB
  • scripts/check_cloudflare_config.py 9 KB
  • scripts/fix_ssl_mode.py 8 KB

Wersje

W bazie nie ma innych skilli o nazwie cloudflare-troubleshooting.

Migawka bazy z 13.11.2026 · wersja paczki e015e714be11 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95cloudflare-dns
    Prowadzi zarządzanie DNS w Cloudflare z integracją Azure: Cloudflare jako autorytatywny DNS, rekordy przez API, tokeny API, proxy, rozwiązywanie problemów, bezpieczeństwo DNS i External-DNS dla Kubernetes.
  • 96cloudflare
    Zarządza strefami DNS, pamięcią podręczną, tunelami i Workers w Cloudflare przez API.
  • 100cloudflare-dns
    Zarządza rekordami DNS w Cloudflare narzędziem flarectl: wyświetla, dodaje, aktualizuje i usuwa rekordy oraz pobiera informacje o strefie.
  • 100cloudflare
    Prowadzi operacje produkcyjne Cloudflare przez serwer MCP Cloudflare API: błędy i wydajność Workers, status buildów i wdrożeń, logi, DNS, kondycja pul load balancera i tunele Zero Trust.
  • 100external-dns
    Prowadzi konfigurację i diagnostykę External-DNS dla Azure DNS, AWS Route53, Cloudflare i Google Cloud DNS, z uwierzytelnianiem, wydajnością i limitami zapytań.
  • 100mcp-server-cloudflare
    Instaluje serwer MCP Cloudflare do zarządzania DNS, Workers i pamięcią podręczną CDN oraz wykonuje jego narzędzia.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.