Cloudflare firewall troubleshooting

​

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

• Multiple % symbols in encoded URL parameters
• Long query strings with special characters
• Automated requests from idle tabs

​

Solution

​

Create the firewall exception

1. Log in to your Cloudflare dashboard
2. Select your domain
3. Navigate to Security > WAF
4. Select Create rule
5. Configure the rule with these settings:

• Field: Hostname
• Operator: equals
• Value: docs.yourdomain.com (replace with your actual docs domain)

• Field: URI Path
• Operator: starts with
• Value: /mintlify-assets/

• Action: Skip
• Select: All remaining custom rules, Managed rules, and Super Bot Fight Mode

6. Enable Log to track matched requests
7. Select Deploy

​

Verify the rule

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

• 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

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