Skip to content
Get help

Common Issues & Debugging

This section outlines frequent issues encountered during the development of Mini Apps and how to resolve them.

Previews Not Rendering

Issue: The app embed does not appear when previewed.

Manifest Embed Example

Cause: This is typically due to an incorrectly formatted or unreachable splashImageUrl in the farcaster.json manifest.

Correct Format

"splashImageUrl": "https://www.example.com/splash_image.png"

Common Mistake

"splashImageUrl": "https://www.example.com//splash_image.png"

Best Practices:

  • Ensure the url is correct without typos. Double slashes, like seen above, will break the mini app preview.
  • Ensure the image is hosted at a publicly accessible URL.
  • Confirm that the image meets the requirements: 200x200 pixels, under 1MB, and in PNG or JPG format.

Preview Tool

To verify your embed, use the Warpcast Frame Developer Tool:

Embed Debugging

Manifest Debugging (farcaster.json)

Ensure your domain's manifest at /.well-known/farcaster.json is properly configured.

Example Manifest

{
  "accountAssociation": {
    "header": "BASE64_HEADER_STRING",
    "payload": "BASE64_PAYLOAD_STRING",
    "signature": "BASE64_SIGNATURE_STRING"
  },
  "frame": {
    "version": "next",
    "name": "MiniKit",
    "iconUrl": "https://example.com/icon.png",
    "splashImageUrl": "https://example.com/splash.png",
    "splashBackgroundColor": "#000000",
    "homeUrl": "https://your-app.com"
  }
}

Checklist:

  • The domain in the payload must match the domain serving the manifest.
  • Ensure all asset URLs (icon, splash) are reachable and correctly formatted.

Incorrect FID or Signature Errors

This is often caused by a farcaster.json file that was signed using the wrong wallet. The signing wallet must match the custody address associated with your Farcaster account.

Issue: You encounter errors related to an invalid FID or failed signature validation.

Cause: The signing wallet does not match the Farcaster custody wallet.

Resolution

To sign with the correct identity, import your Farcaster custody key into an external wallet:

Manifest Signing Utility

Run the following to initiate the manifest signing workflow:

 npx create-onchain --manifest

This CLI will open the signing UI in your browser and update local .env values automatically.

Developer Tools

Warpcast Frame Debugger

Preview how your Mini App renders inside Farcaster:

Farcaster Debugging