This OG image debugger checklist works from the crawler’s side, because that is where a blank preview is decided. A social network fetches your page, reads the tags, fetches the image URL once, and caches whatever came back. Work through the steps in order and stop at the first failure.
1. Check the tags in the raw HTML
Run curl -s https://example.com/post | grep og:. If the tags are missing, they are being added after the page loads. The Open Graph protocol places them in the <head> of the served document, so render them on the server. In Next.js, generateMetadata does this.
2. Check the image URL is absolute
og:image should be a full https URL, not /images/card.png. Duplicate tags are allowed, but ogp.me states that the first tag from top to bottom wins on conflict, so a leftover tag from an SEO plugin can override yours.
3. Fetch the image the way a crawler does
curl -sI "https://app.jsontoimg.com/api/v1/img/<design-id>?headline=Hello&version=1&sig=..."You want 200 and an image Content-Type (MDN reference). Anything else maps to a row in the table below.
4. Read the status code
| Status | Meaning for a signed jsontoimg URL | Fix |
|---|---|---|
| 200 | Image served | Problem is cache or tags; go to step 6 |
503 with Retry-After |
First render still running | Request it again; crawlers retry, but warm the URL after publishing |
| 401 | Signature does not match the query string | A proxy or CMS re-encoded a parameter; use the minted url verbatim |
| 400 | Duplicate query key, such as two headline parameters |
Remove the duplicate before the URL reaches the page |
| 402 | Workspace is out of image quota | Buy a prepaid pack or upgrade; renders stop at quota |
5. Rule out blocked crawlers
If the page or image sits behind a login, a staging password, or a robots.txt rule that disallows the crawler, the fetch fails before it reaches the image. Test from a network outside your VPN.
6. Re-scrape and bust the cache
Networks cache previews. After a fix, re-fetch in the Facebook Sharing Debugger or the LinkedIn Post Inspector. If the old image persists, change the image URL itself. A signed jsontoimg URL changes whenever the title or version changes.
7. Add the alt text
The protocol asks for og:image:alt next to og:image. It does not fix a blank card, but it is on the same checklist for a reason.
The end-to-end design of the flow is in the Open Graph image generator guide.
FAQ
Why is my OG image not showing?
The most common causes are tags added after page load, a relative image URL, an image URL that returns a non-200 status to the crawler, or a cached preview from before the fix.
What does a 503 on a signed jsontoimg URL mean?
The first render of that exact URL is still running. The response carries a Retry-After header, and crawlers and the Sheets and Airtable add-ons retry on it.
Why does a signed URL return 401?
The signature covers the query string. If anything re-encodes, reorders, or edits a parameter, verification fails with 401 and no render happens.
How do I refresh a cached share preview?
Re-scrape the page in the Facebook Sharing Debugger or LinkedIn Post Inspector. If the cached image sticks, change the image URL, for example by bumping the template version.
Related Resources
- How JSON-to-image conversion works — the pillar guide
- Open Graph image generator guide — the full flow
- URL rendering docs — status code reference
- Pricing — what counts as a credit