Troubleshoot Open Graph images

60-second triage

• View source (not DevTools Elements after JS) — is og:image an absolute https://…/api/og/… URL?
• Does twitter:image match og:image exactly?
• curl -sI the image URL — HTTP 200 and content-type: image/png?
• Open the image URL in a private window — does the title match the page H1?
• If HTML and PNG are correct but Slack/FB are wrong → rescrape / version the URL (below).

curl -sI "https://YOUR_PAGE" | head -5
# then extract og:image and:
curl -sI "PASTE_OG_IMAGE_URL" | grep -iE 'HTTP|content-type|cache-control'

Symptom: blank or missing preview

Scrapers only see the first HTML response. Client-only React, late useEffect meta, or a SPA without prerender will look fine in Chrome and empty in Slack.

• Fix: set metadata in Next generateMetadata, Astro layout, Hugo partial, or another SSR/SSG head.
• Relative paths like /og.png resolve against the wrong host for many bots — always absolute HTTPS.
• Confirm the deployed host (www vs apex) matches the URL you are scraping.

Symptom: wrong title / old product name on the card

OGKit renders whatever is in the query string. Updating page copy without updating the OGKit title param leaves the old card forever (and platforms may cache it).

• Align title/subtitle with the visible H1 + one-line summary.
• After changing fields, the image URL changes → treat as a new cache object.
• Static sites (Astro/Hugo): rebuild + redeploy before rescraping.

Symptom: 401 / 403 / watermark / quota on the image URL

• Missing or wrong key= — check server env (OGKIT_KEY), not NEXT_PUBLIC_ / PUBLIC_.
• Signed URLs required on the key but sig= missing or canonical string wrong — see Signed URLs guide.
• Domain allowlist enabled — add the page’s host (and www variant if used).
• During open access, demo=1 works without a key for evaluation; production still prefers a rotatable key.

Symptom: Facebook / LinkedIn / Slack stuck on the old card

This is almost never an OGKit render bug. Platforms cache unfurls aggressively. Caching & rescrape covers headers; here is the conversion path:

• 1) Confirm live HTML already points at the new image URL.
• 2) Facebook Sharing Debugger → Scrape Again.
• 3) LinkedIn Post Inspector on the canonical URL.
• 4) Slack: delete the unfurl and reshare; if stuck, change the image URL (new title or v=2026-08-13) and reshare.
• 5) Avoid random _t= timestamps in production — use intentional v= only when you need a bust.

Next.js-specific gotchas

• Do not ship both opengraph-image.tsx and an OGKit URL for the same route without knowing which wins.
• generateMetadata must run on the server — never import your og helper into a Client Component.
• Static export / ISR: ensure the HTML that crawlers hit includes the tags (not only a client shell).

Astro & Hugo (static) gotchas

• Empty getenv / import.meta.env at build → key= blank baked into every page.
• Theme default og:image conflicting with your partial — check for duplicate meta tags.
• Title changes require rebuild + deploy before any rescrape will help.

Still stuck?

Use Playground to prove the template+fields look right, Tools for debugger links, and Docs for status codes. If HTML + PNG are correct and rescrape was forced, wait for residual cache or version the image URL once more.