​
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

Always use the user’s connected wallet for optimal experience. You can do this either by using OnchainKit’s Wallet component or Wagmi hooks. Below is a Wagmi hook example:
App.tsx
import { useAccount } from 'wagmi';

function MyComponent() {
  const { address, isConnected } = useAccount();
  
  const walletConnected = isConnected;
  
  const userAddress = address; // Cryptographically verified
  
  return (
    <div>
      {walletConnected && (
        <p>Wallet: {userAddress}</p>
      )}
      {/* Use wallet data for secure operations */}
    </div>
  );
}

​
5. Gesture Conflicts and App Dismissal Issues

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

​
6. Mobile Testing & Debugging

Eruda Mobile Console Setup: Add Eruda for mobile console debugging during development:
App.tsx
import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    // Only load Eruda in development and not on localhost
    if (typeof window !== 'undefined' && 
        process.env.NODE_ENV === 'development' && 
        !window.location.hostname.includes('localhost')) {
      import('eruda').then((eruda) => eruda.default.init());
    }
  }, []);

  return (
    <div>
      {/* Your app content */}
    </div>
  );
}
Mobile Testing Workflow:
  1. Deploy to production or use ngrok for local testing
  2. Share the mini app in a Farcaster DM to yourself
  3. Open in mobile client (Base App, Farcaster)
  4. Use Eruda console for debugging on mobile
  5. Test across multiple clients for compatibility
Testing Checklist:
  • App loads correctly on mobile devices
  • Touch interactions work properly
  • Viewport is correctly sized
  • Images load and display correctly
  • Console shows no critical errors

​
Advanced Troubleshooting

CBW Validator Tool: Use the Coinbase Wallet validator for Base App compatibility analysis. This AI-powered tool can identify unsupported patterns and suggest improvements. Complete Manifest Example:
farcaster.json
{
  "accountAssociation": {
    "header": "your-farcaster-header",
    "payload": "your-farcaster-payload", 
    "signature": "your-farcaster-signature"
  },
    "baseBuilder": {
    "allowedAddresses": ["0x..."]
  },
  "frame": {
    "name": "Your Mini App",
    "iconUrl": "https://yourapp.com/icon.png",
    "homeUrl": "https://yourapp.com",
    "imageUrl": "https://yourapp.com/og.png",
    "buttonTitle": "Launch App", 
    "description": "Your app description under 130 characters",
    "primaryCategory": "social",
    "tags": ["tag1", "tag2"]
  }
}

​
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