mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
e442b85b5e
* docs: apply brand tone and writing style fixes to subpath proxy pages * docs: fix duplicated word and double space in custom portal doc --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
100 lines
3.4 KiB
Plaintext
100 lines
3.4 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 the 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 the 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 that you enabled and deployed the rule.
|
|
|
|
## Common mistakes
|
|
|
|
- Using the `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. Explicitly include it in the skip action.
|
|
- Setting the wrong hostname. It 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 that your Cloudflare Worker (if using a custom subpath) sets the `Host` header to your `<subdomain>.mintlify.site` target instead of passing through the original request's `Host` header.
|
|
3. Temporarily set Security Level to "Essentially Off" to confirm that 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
|
|
```
|