Skip to main content
When you enable Vercel Bot Protection on a project that hosts a Mini App, Farcaster’s server-side requests (manifest fetches, embed scraping, OG images) get blocked because they can’t solve JavaScript challenges. This causes broken embed cards, failed discovery, and the Mini App getting stuck on the splash screen. The fix is to create WAF bypass rules for the paths Farcaster needs to access.
Warning The Vercel WAF evaluates before your application code runs. Bot-allowlisting logic in Next.js middleware will not help — the request is blocked before your middleware executes.

​
Paths that need bypass rules

​
Creating bypass rules

Custom WAF rules execute before managed rulesets, so a bypass rule on a path will skip bot protection entirely for matching requests.
1

Open Firewall configuration

In the Vercel Dashboard, go to your project, open Firewall in the sidebar, click ⋯ (top right) then Configure, then Add New… and Rule.
2

Rule 1: Bypass the homepage

  • Name: Allow miniapp launch and embed scrape
  • If: Path — equals — /
  • Then: Bypass
If your homeUrl is not /, bypass that path instead. If you have multiple pages with fc:miniapp meta tags, combine them with OR conditions.
3

Rule 2: Bypass .well-known paths

  • Name: Allow Farcaster manifest
  • If: Path — starts with — /.well-known/
  • Then: Bypass
4

Rule 3: Bypass OG image endpoint

  • Name: Allow OG image generation
  • If: Path — equals — /api/og
  • Then: Bypass
Skip this rule if your embed image is a static file or hosted externally.
5

Rule 4: Bypass auth endpoint

  • Name: Allow miniapp auth
  • If: Path — equals — your auth endpoint path
  • Then: Bypass
Only needed if you have a custom auth endpoint (not a Farcaster-defined route). Replace the path with whatever your app uses. Consider scoping with a User-Agent condition (e.g. User Agent contains farcaster) to narrow the bypass surface.
6

Save and publish

Click Save Rule for each rule, then Review Changes and Publish.
Start with the Log action first to verify the rules match expected traffic, then switch to Bypass.
Bypass rules can only be created via the Vercel Dashboard or REST API. vercel.json only supports challenge and deny — not bypass.

​
Hobby plan (3 rule limit)

Combine all three rules into one using OR conditions:
  • If: Path equals / OR Path starts with /.well-known/ OR Path equals /api/og
  • Then: Bypass

​
Troubleshooting

  • Splash screen hangs: The homeUrl is likely being challenged (Rule 1 missing) or the manifest fetch is failing (Rule 2 missing).
  • Embed card broken in feed: The fc:miniapp meta tag scrape or OG image fetch is being blocked (Rule 1 or Rule 3).
  • App not appearing in directory: Manifest fetch is being blocked (Rule 2).
  • Rules not working: Check the Firewall traffic view in the Vercel Dashboard. Ensure bypass rules appear above any deny/challenge rules targeting the same paths and that path values exactly match (use Log mode to verify).

​
Alternatives

IP-based allowlisting is not recommended — Farcaster doesn’t publish stable IP ranges and they can change without notice. Hosted manifests redirect /.well-known/farcaster.json to Farcaster’s servers, but the redirect may not execute before the WAF blocks the request. Always keep the .well-known bypass rule regardless. Attack Challenge Mode is a separate feature that challenges all visitors during DDoS attacks. The same bypass rules work for both.

Related topics

deployToVercelvercelDeploymentLogsvercelDeploymentStatusListen for @bot MentionsBot Replying with Frames