From f6cd7bce27e4f1c597eac8e874ea324c197387bd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 22 Oct 2025 20:53:05 +0000 Subject: [PATCH 1/3] Update deploy/cloudflare-firewall-troubleshooting.mdx --- .../cloudflare-firewall-troubleshooting.mdx | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 deploy/cloudflare-firewall-troubleshooting.mdx diff --git a/deploy/cloudflare-firewall-troubleshooting.mdx b/deploy/cloudflare-firewall-troubleshooting.mdx new file mode 100644 index 000000000..b6d19d24e --- /dev/null +++ b/deploy/cloudflare-firewall-troubleshooting.mdx @@ -0,0 +1,102 @@ +--- +title: Cloudflare firewall troubleshooting +description: Resolve 500 errors and slow navigation caused by Cloudflare blocking Mintlify assets +--- + +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. Select **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. Select **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 + + +Avoid these configuration errors that prevent the rule from working: + + +- 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 +``` From e70182effd717deef2f04deb9751bfb635bb505b Mon Sep 17 00:00:00 2001 From: Dean from Mintlify Date: Wed, 22 Oct 2025 14:28:47 -0700 Subject: [PATCH 2/3] Update deploy/cloudflare-firewall-troubleshooting.mdx Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- deploy/cloudflare-firewall-troubleshooting.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy/cloudflare-firewall-troubleshooting.mdx b/deploy/cloudflare-firewall-troubleshooting.mdx index b6d19d24e..8ae777da2 100644 --- a/deploy/cloudflare-firewall-troubleshooting.mdx +++ b/deploy/cloudflare-firewall-troubleshooting.mdx @@ -1,6 +1,6 @@ --- -title: Cloudflare firewall troubleshooting -description: Resolve 500 errors and slow navigation caused by Cloudflare blocking Mintlify assets +title: "Cloudflare firewall troubleshooting" +description: "Resolve 500 errors and slow navigation caused by Cloudflare blocking Mintlify assets" --- 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. From b4ff601530ff5e9172df724f4dbdecec9ba1a756 Mon Sep 17 00:00:00 2001 From: Dean from Mintlify Date: Wed, 22 Oct 2025 14:29:00 -0700 Subject: [PATCH 3/3] Update deploy/cloudflare-firewall-troubleshooting.mdx Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- deploy/cloudflare-firewall-troubleshooting.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/deploy/cloudflare-firewall-troubleshooting.mdx b/deploy/cloudflare-firewall-troubleshooting.mdx index 8ae777da2..624552cab 100644 --- a/deploy/cloudflare-firewall-troubleshooting.mdx +++ b/deploy/cloudflare-firewall-troubleshooting.mdx @@ -69,10 +69,6 @@ If issues persist, verify your rule configuration: ## Common mistakes - -Avoid these configuration errors that prevent the rule from working: - - - 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