mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
f14cca3b52
* Standardize style: 'Click' to 'Select' for Mintlify UI; split long sentences Generated-By: mintlify-agent * Revert 'select' back to 'click' for UI interactions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Fix select→click for UI elements across docs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
100 lines
3.3 KiB
Plaintext
100 lines
3.3 KiB
Plaintext
---
|
|
title: "Cloudflare firewall troubleshooting"
|
|
description: "Troubleshoot blocked requests and resolve Cloudflare WAF rule conflicts when serving Mintlify documentation through Cloudflare Workers."
|
|
keywords: ["Cloudflare WAF", "firewall rules", "Bot Fight Mode", "403 errors"]
|
|
---
|
|
|
|
If your documentation site shows 500 errors after a few seconds or experiences slow navigation, Cloudflare's firewall may be blocking requests to Mintlify assets.
|
|
|
|
## Symptoms
|
|
|
|
- Documentation page loads initially but crashes with a 500 error after 30-60 seconds
|
|
- Slow or broken client-side navigation between pages
|
|
- 403 errors in browser console for requests to `/mintlify-assets/*` paths
|
|
- Cloudflare security challenge messages about "malformed data" or "suspicious URL patterns"
|
|
|
|
## Root cause
|
|
|
|
Cloudflare's Web Application Firewall (WAF) and Bot Fight Mode can flag Mintlify asset requests as suspicious due to:
|
|
|
|
- Multiple `%` symbols in encoded URL parameters
|
|
- Long query strings with special characters
|
|
- Automated requests from idle tabs
|
|
|
|
## Solution
|
|
|
|
Create a Cloudflare firewall rule to exempt Mintlify assets from security checks.
|
|
|
|
### Create the firewall exception
|
|
|
|
1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com/)
|
|
2. Select your domain
|
|
3. Navigate to **Security > WAF**
|
|
4. Click **Create rule**
|
|
5. Configure the rule with these settings:
|
|
|
|
**Rule name:** Allow Mintlify assets
|
|
|
|
**When incoming requests match:**
|
|
- Field: `Hostname`
|
|
- Operator: `equals`
|
|
- Value: `docs.yourdomain.com` (replace with your actual docs domain)
|
|
|
|
**And:**
|
|
- Field: `URI Path`
|
|
- Operator: `starts with`
|
|
- Value: `/mintlify-assets/`
|
|
|
|
**Then:**
|
|
- Action: `Skip`
|
|
- Select: `All remaining custom rules`, `Managed rules`, and `Super Bot Fight Mode`
|
|
|
|
6. Enable **Log** to track matched requests
|
|
7. Click **Deploy**
|
|
|
|
### Verify the rule
|
|
|
|
After deploying:
|
|
|
|
1. Open your documentation site in a browser
|
|
2. Leave the page idle for 2-3 minutes
|
|
3. Navigate between pages
|
|
4. Check browser console for any 403 errors
|
|
|
|
If issues persist, verify your rule configuration:
|
|
|
|
- Ensure the hostname exactly matches your docs domain
|
|
- Confirm the URI path uses `starts with` (not `contains`)
|
|
- Do not include wildcards (`*`) in the path value
|
|
- Verify the rule is enabled and deployed
|
|
|
|
## Common mistakes
|
|
|
|
- Using `contains` operator with `/mintlify-assets/*` - The `*` is treated as a literal character, not a wildcard
|
|
- Using `equals` for URI Path - This only matches the exact path `/mintlify-assets/` and not subpaths
|
|
- Forgetting to skip Bot Fight Mode - This must be explicitly included in the skip action
|
|
- Wrong hostname - Must match your actual documentation domain
|
|
|
|
## Additional troubleshooting
|
|
|
|
If the firewall exception doesn't resolve the issue:
|
|
|
|
1. Check Cloudflare's **Security > Events** log for blocked requests
|
|
2. Verify your Cloudflare Worker (if using custom subpath) correctly forwards the `Host` header
|
|
3. Temporarily set Security Level to "Essentially Off" to confirm Cloudflare is the cause
|
|
4. Review any custom Page Rules that might override the firewall exception
|
|
|
|
## Example working configuration
|
|
|
|
```
|
|
Rule: Allow Mintlify assets
|
|
Status: Enabled
|
|
|
|
When incoming requests match:
|
|
(http.host eq "docs.flashnet.xyz" and starts_with(http.request.uri.path, "/mintlify-assets/"))
|
|
|
|
Then:
|
|
Skip: All remaining custom rules, Managed rules, Super Bot Fight Mode
|
|
Log: Enabled
|
|
```
|