Skip to main content

​
How to debug

  • Step 1: First, remove your miniapp. Then re-add it and re-enable notifications. Afterwards, retry notifications and send to yourself.
  • Step 2: Test notifications with another user. Send them the miniapp link, confirm the receiving user has enabled notifications for their Farcaster account, and then try sending another notification just to their FID.
  • Step 3: If the previous two steps have not resolved your situation, please reach out to our Developer Slack for support. In your Slack message, please share a screenshot of the console (right click on page, then click “inspect”).

​
FAQ

Developers often test enabling notifications with their own account using a localtunnel or ngrok domain (sometimes without even realizing they’ve enabled notifications on their test URL). When developers change their domain to a Vercel domain or something else, their notification token becomes invalid and results in failures from Farcaster’s servers (usually an “invalid domain” error).
This usually happens when the target_url in your notification request uses a different domain than your app is registered on. A common cause is inconsistently using the www. prefix — www.example.com and example.com are treated as separate domains. When Farcaster returns a target_url_mismatch error, the affected tokens are permanently invalidated. Ensure your target_url always uses the exact domain from your farcaster.json manifest. Once you’ve resolved the underlying domain or farcaster.json issue, reach out to Neynar support to get your invalidated tokens re-activated.
Please see response to “Why am I not receiving a notification?” above. Additionally, there are instances where a user may be on an old mini app domain that has phased out. Users who do receive notifications are usually on the most recent domain.
Add the canonicalDomain field to the farcaster.json manifests on both your old and new domains, pointing to the new domain. When Farcaster picks up the updated manifest, it automatically migrates all existing notification tokens from the old domain to the canonical domain — existing users do not need to re-enable notifications. If you use the same Neynar app (and therefore the same webhookUrl) on both domains, notifications will work from the new domain with no additional configuration. See the domain migration guide for the full steps.