> ## Documentation Index > Fetch the complete documentation index at: https://base-a060aa97-eb-mini-app-ia-overhaul.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Common Issues & Debugging > Frequent issues encountered during Mini App development and their solutions ## Prerequisites & Setup Verification Ensure your Mini App has the foundational requirements in place. ### Required Files and Structure ```html 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 `` 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: ```ts 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