The message itself does not identify why the tool failed. Treat it as a generic symptom and test the public fetch, JSON parsing, schema, and association separately. Preserve exact evidence before changing anything.
It checks the public manifest, page embed, response headers, and referenced assets. It does not change your app, prove client runtime behavior, or authorize repair work.
Stop as soon as a step fails. Fix it, fetch the public URL again, and preserve the before and after response. A generic message can otherwise obscure which layer failed.
Request https://your-domain/.well-known/farcaster.json without a browser session. A direct JSON response and Farcaster's documented temporary redirect to a hosted manifest are both valid patterns. Record the full redirect chain; the final response must contain usable JSON, not HTML, a login page, an interstitial, or a JavaScript challenge. Record theContent-Type, then parse the exact bytes—the header alone proves nothing.
Farcaster fetches the manifest server-side. A JavaScript challenge that works in your own browser can still block that fetch. On Vercel, the WAF runs before application middleware; use the documented narrowly scoped bypass for /.well-known/farcaster.json. On another provider, add an equivalent exception only if the external fetch actually shows a challenge. Do not disable protection site-wide or rely on an IP allowlist.
The accountAssociation.payload.domain value must exactly match the FQDN serving the manifest, including any subdomain; apex and www are different identities. As a clean launch convention, keep homeUrl and the public launch URL on the intended canonical host. Use Farcaster's documented migration flow when moving domains. Regenerate the association instead of editing encoded fields by hand, and verify its signature—decoding a payload is not cryptographic verification.
Parse the raw response with a strict JSON parser. Remove trailing commas and comments. Use the version documented by Farcaster's current publishing guide—currently 1, not a semantic version such as 1.0.0—and check required fields including name,homeUrl, and iconUrl.
A URL-shaped string is not enough. Each image must return an image response at its final URL. Farcaster's publishing guide calls for a 1024×1024 PNG icon without alpha, portrait 1284×2778 screenshots, and 1200×630 hero or Open Graph artwork. Check MIME type, bytes, dimensions, aspect ratio, and transparency rather than trusting the filename.
Proof to keep: final URL, status, MIME, byte count, dimensions, and image hash.The domain manifest and fc:miniapp page metadata solve different problems. The manifest identifies and configures the app; the embed makes a shared page launchable. Validate both, including button.title, button.action.type, the required action name, optional action URL, and image. Do not treat a valid embed as proof that the manifest can be retrieved.
After each fix, fetch the deployed bytes again from outside your authenticated browser session. Then refresh the official manifest tool. Cache can delay an observation, but it is only a possibility—not a diagnosis. If the exact deployed response validates and the tool still fails, report the timestamp, redirect chain, final status, and sanitized validation evidence upstream.
Proof to keep: before-and-after hashes and timestamps. Never publish private keys, auth or admin tokens, payment signatures, or unrelated secrets; link the already-public manifest and sanitized diagnostics.Manifest retrieval does not prove that sdk.actions.ready() runs, that a client can render the app, or that add-app and notification flows work. Test those client behaviors after the public manifest and embed evidence is clean.
Likewise, a working browser tab does not prove that Farcaster's server-side fetch can pass your bot protection. Keep transport, schema, assets, and runtime as separate evidence layers.
Product schemas and requirements change. These links are the source of truth; this guide is a debugging sequence, not a substitute for current platform documentation.
TLMNT first reproduces one integration failure and confirms the scope. You grant only the access needed for that repair. Payment is requested only after you receive before-and-after evidence and verify the fix. Submitting the request form authorizes neither access nor payment. No verified fix means no payment.