​
Prerequisites & Setup Verification

Ensure your Mini App has the foundational requirements in place.

​
Required Files and Structure

your-domain.com/
├── .well-known/
│   └── farcaster.json          # Required manifest file
├── your-app/
│   ├── index.html              # Your app entry point
│   └── ...                     # Your app files

​
Environment Setup Checklist

  • Domain is accessible via HTTPS
  • Manifest file exists at /.well-known/farcaster.json
  • All image URLs are publicly accessible

​
Basic Validation Steps

  1. Test manifest accessibility: visit https://yourdomain.com/.well-known/farcaster.json
  2. Validate JSON syntax with JSONLint
  3. Ensure your app loads without console errors

​
Quick Diagnostic Workflow

  • Not appearing in search? → App Discovery & Indexing Issues
  • Not rendering as an embed? → Embed Rendering Issues
  • Wallet connection problems? → Wallet Connection Problems
  • Need mobile testing tools? → Mobile Testing & Debugging
  • Changes not appearing? → Manifest Configuration Problems
  • App closes on gestures? → Gesture Conflicts and App Dismissal Issues

​
Detailed Problem Solutions

​
1. App Discovery & Indexing Issues

Problem: Your Mini App doesn’t appear in search results or app catalogs. Root cause: Missing or incomplete manifest configuration. Solution: Ensure your manifest includes all required fields (see Manifest feature guide). Critical requirements:
  • primaryCategory is required for searchability and category pages
  • accountAssociation is required for verification
App Indexing Requirements:
  1. Complete your manifest setup
  2. Share your Mini App URL in a post
  3. Indexing can take up to 10 minutes
  4. Verify appearance in app catalogs
Caching Issues — Changes Not Appearing: Farcaster clients may cache manifest data for up to 24 hours. Re‑share to trigger a refresh and allow ~10 minutes.

​
2. Manifest Configuration Problems

Image Display Issues:
  1. Test image accessibility in incognito
  2. Verify image format (PNG, JPG, WebP supported)
  3. Check dimensions
  4. Ensure HTTPS URLs only

​
3. Embed Rendering Issues

Problem: Your Mini App URL doesn’t render as a rich embed when shared. Root cause: Incorrect or missing fc:frame metadata. Solution: Use name="fc:frame" meta tag in <head> and validate using the Embed Tool.

​
4. Wallet Connection Problems

Prefer MiniKit with OnchainKit Wallet or Wagmi hooks. MiniKit includes wagmi providers; avoid double configuration.

​
5. Gesture Conflicts and App Dismissal Issues

Disable native gestures when calling ready if you use swipe/drag interactions: 
await sdk.actions.ready({ disableNativeGestures: true });

​
6. Mobile Testing & Debugging

Use Eruda for mobile debugging; remove before production deployment.

​
Advanced Troubleshooting

AI‑Assisted Debugging: Use the CBW MiniApp Validator prompt to scan for unsupported patterns.

​
Success Verification

Basic functionality and discovery/sharing checklists: confirm load, images, wallet, manifest endpoint, embed rendering, and search presence.

​
Getting Additional Help

  • Mini App Debug Tool
  • Mini App Embed Tool
  • JSONLint
  • Eruda
  • Base Discord — #minikit channel