mintlify__docs/deploy/cloudflare-firewall-troubleshooting.mdx

---
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 that you enabled and deployed the rule

## 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 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 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
```