1. Start with the response, not the screenshot
Run the public URL through the Open Graph checker for a quick title, description, image, and resolved-URL sanity check. It uses Microlink’s normalized metadata: a healthy score does not prove that every raw OG or Twitter tag is present, unique, or accessible to a specific platform crawler.
Then inspect what the server sends without JavaScript. These commands run in macOS/Linux shells with curl and file. They save temporary files under /tmp/og-*; replace the sample URLs before running.
Inspect page HTML, crawler response, and image bytes
# Replace these two URLs with the exact public page and image.
PAGE_URL='https://example.com/blog/image-api-v2'
IMAGE_URL='https://example.com/social/image-api-v2.png'
# GET the initial HTML, follow redirects, and save headers from each hop.
curl -sS -L --max-redirs 5 --max-time 30 --compressed \
-D /tmp/og-page-headers.txt -o /tmp/og-page.html \
-w 'Page: %{http_code} %{content_type} %{url_effective}\n' "$PAGE_URL"
# Read the complete source: inspect <head>, duplicates, and redirect headers.
cat /tmp/og-page-headers.txt
cat /tmp/og-page.html
# Compare a crawler user agent; this does NOT reproduce its IP or cache.
curl -sS -L --max-redirs 5 --max-time 30 --compressed \
-A 'facebookexternalhit/1.1' \
-D /tmp/og-bot-headers.txt -o /tmp/og-bot.html "$PAGE_URL"
diff -u /tmp/og-page.html /tmp/og-bot.html
# GET the actual image, not just HEAD (servers may handle them differently).
curl -sS -L --max-redirs 5 --max-time 30 \
-D /tmp/og-image-headers.txt -o /tmp/og-image \
-w 'Image: %{http_code} %{content_type} %{size_download} bytes\n' "$IMAGE_URL"
cat /tmp/og-image-headers.txt
file /tmp/og-imageWhat a healthy response looks like
The final page returns 200 with HTML containing the intended tags in its head. The image returns 200 with an image Content-Type and recognizable image bytes. Check each redirect’s Location, any X-Robots-Tag header, and the relevant robots.txt. A 200 challenge page is still a failure. A user-agent comparison is a clue; real crawler logs and platform inspection are stronger evidence.
2. Match the symptom to a concrete failure
No title or description, even though the browser looks right
Evidence to look for: The initial HTML has no og:title or og:description. Tags only appear in DevTools after JavaScript runs, or the server sends the same app shell for every route.
Fix: Put page-specific tags in the server-rendered or statically generated head. A client-side effect is not a reliable way to serve social metadata. Compare the raw response with the DOM after hydration.
Use the HTML baseline →The title is right, but the image is missing
Evidence to look for: The og:image URL returns 403, 404, a login page, or an HTML fallback with status 200. Signed URLs can expire after your own browser has cached the image.
Fix: Publish a stable, absolute HTTPS image URL that works without cookies. Serve real image bytes with the matching Content-Type. Use JPEG or PNG for broad compatibility; avoid SVG, data URLs, and relative paths for share cards.
Inspect the image response →The preview works locally but a crawler cannot fetch it
Evidence to look for: The public URL returns a challenge, 401/403/429, times out, or redirects to authentication. Your browser session may be hiding the problem.
Fix: Check CDN/WAF and origin logs for the real crawler request. Make the intended public page and image reachable without authentication, and review robots rules on both hosts. Scope any firewall exception to verified crawlers and public routes; do not expose private content.
Compare crawler responses →A post shows the homepage title or the wrong article image
Evidence to look for: The response contains competing og:title or og:image tags from a layout, SEO plugin, and page component. Multiple og:image values can also be intentional: Open Graph gives the first value preference.
Fix: Give one template or metadata API ownership of each page’s tags. Remove accidental duplicates and place the intended primary image first, with its width, height, and alt tags immediately after it. Inspect every tag; normalized checker output can hide conflicts.
Check framework inheritance →The image is present but the headline is cropped or tiny
Evidence to look for: The important text sits at an edge, the source image is a small icon, or the file’s real dimensions disagree with og:image:width and og:image:height.
Fix: Start with a dedicated 1200 × 630 landscape image. Keep the subject and short headline toward the center, and inspect a thumbnail-sized version. Set dimension tags to the actual file size. This is a practical baseline, not a guarantee of identical crops on every platform.
Compare card examples →Different URL variants produce different cards
Evidence to look for: HTTP, www, trailing-slash, locale, or campaign URLs resolve differently. og:url still identifies a staging host or the homepage instead of the article.
Fix: Choose the intended public URL for this content. Align redirects, rel=canonical, and og:url with it, preserving distinct locales or articles where appropriate. Remove redirect loops and unnecessary hops. Test the exact URL people share and the final destination separately.
Align the URL tags →The source is fixed, but an existing share still looks old
Evidence to look for: The current HTML and image response are correct, while one platform keeps displaying an earlier title or image. The HTML CDN cache, image cache, and platform cache are separate layers.
Fix: Purge stale responses at your own CDN first. If the image bytes changed, publish a new image filename and update og:image and twitter:image. Request a fresh inspection on the affected platform; existing posts or messages may keep their original preview.
Follow the cache refresh sequence →3. Copy a complete HTML baseline
The Open Graph protocol’s four basic required properties are og:title, og:type, og:image, and og:url. Add a useful description, image details, and explicit X card metadata. This example is an article; use website for a homepage or general product landing page.
Article metadata in the document head
<!-- Put these in <head>; replace every example.com URL and text. --> <title>Image API v2: smaller files, same detail | Acme</title> <meta name="description" content="See the new image API, compare output quality, and follow the v1 migration steps." /> <link rel="canonical" href="https://example.com/blog/image-api-v2" /> <meta property="og:type" content="article" /> <meta property="og:site_name" content="Acme" /> <meta property="og:url" content="https://example.com/blog/image-api-v2" /> <meta property="og:title" content="Image API v2: smaller files, same detail" /> <meta property="og:description" content="Compare output quality and migrate from v1 with working code examples." /> <meta property="og:image" content="https://example.com/social/image-api-v2.png" /> <meta property="og:image:type" content="image/png" /> <meta property="og:image:width" content="1200" /> <meta property="og:image:height" content="630" /> <meta property="og:image:alt" content="Image API v1 and v2 output shown side by side." /> <meta name="twitter:card" content="summary_large_image" /> <meta name="twitter:title" content="Image API v2: smaller files, same detail" /> <meta name="twitter:description" content="Compare output quality and migrate from v1 with working code examples." /> <meta name="twitter:image" content="https://example.com/social/image-api-v2.png" /> <meta name="twitter:image:alt" content="Image API v1 and v2 output shown side by side." />
Replace the sample text and URLs, upload the referenced image, and use its real dimensions. HTML-escape dynamic values (for example, & for an ampersand and " for a double quote inside an attribute). OG tags use property; Twitter card tags use name. The twitter: prefix still applies to X.
Keep canonical and OG URLs aligned for this page. Canonical tags express a preferred search URL; og:url identifies the shared object. Neither one fixes an inaccessible page or performs an HTTP redirect.
4. Fix metadata ownership in Next.js
In the App Router, export metadata from a server page or layout. Nested metadata objects are not deeply merged: setting a page’s openGraph object replaces the inherited object, so a title-only override can lose a parent image or description. Define the complete object or deliberately reuse shared values.
Self-contained Next.js App Router page
// app/blog/image-api-v2/page.tsx — keep this a Server Component.
import type { Metadata } from "next";
const url = "https://example.com/blog/image-api-v2";
const title = "Image API v2: smaller files, same detail";
const description = "Compare output quality and migrate from v1 with working code examples.";
const image = "https://example.com/social/image-api-v2.png";
export const metadata: Metadata = {
title,
description,
alternates: { canonical: url },
openGraph: {
type: "article",
siteName: "Acme",
url,
title,
description,
images: [{
url: image,
width: 1200,
height: 630,
alt: "Image API v1 and v2 output shown side by side.",
}],
},
twitter: {
card: "summary_large_image",
title,
description,
images: [{ url: image, alt: "Image API v1 and v2 output shown side by side." }],
},
};
export default function Page() {
return <h1>{title}</h1>;
}For dynamic content, use generateMetadata with that page’s resolved data instead. Check for file-based opengraph-image and twitter-image conventions, which have higher priority than configuration metadata. If a UI needs client-side state, move that UI into a child Client Component.
Run your production build and inspect the deployed response again. Next.js versions that stream dynamic metadata treat HTML-limited bots specially; custom bot configuration can change the result. Verify the actual crawler response rather than assuming the browser’s hydrated head is sufficient.
6. Refresh the right cache
- Deploy the HTML and image. Re-run the GET checks against the public URL and inspect CDN cache headers. Purge your own stale page or asset cache if necessary.
- If an image changed, give it a versioned path such as
/social/image-api-v2-r2.png. Update both image tags. Keep the page’s canonical and OG URL stable unless the page itself moved. - Inspect the exact shared URL using the relevant platform tool below, then test a new share. A browser hard refresh or a successful check here does not invalidate another service’s cache.
Use Sharing Debugger, inspect the fetched URL and warnings, and request “Scrape Again” after fixing the response. Login may be required.
Run the URL through Post Inspector to inspect and refresh its preview information. Test a new post; already-published posts may retain their original card.
X
Check twitter:card, the image response, and Twitterbot access. Use the explicit Twitter tags in the HTML baseline above. There is no universal immediate cache-purge guarantee; verify with a new share after recrawling.
Slack and other chat apps
Treat unfurl caches and workspace settings separately. Check whether previews are enabled, then test a newly sent link after correcting the public response. A previously sent message may keep its existing unfurl.
7. Verify before the next share
- The exact shared URL reaches the intended public HTML without authentication, loops, or bot challenges.
- The raw head contains one intended title, description, type, and URL, with image tags in the intended order.
- The image is public, uses a stable absolute HTTPS URL, and returns the expected format and actual dimensions.
- The canonical, final destination, and og:url identify the intended page, including on URL variants.
- The production response, checker output, and relevant platform inspection have all been checked after deployment.
8. Fix with your coding agent
Copy this prompt into Claude Code, Codex, or another coding agent with access to your project. Replace the bracketed fields with your public URL and the problem you see. Add checker results if you have them.
AI debugging prompt
Debug and fix this project's Open Graph and social share metadata. Page URL: [paste the exact public URL people share] Observed problem/platform: [describe the wrong preview, or say "audit this page"] Expected title, description, and image: [optional; otherwise use the page's real content and existing brand assets] Checker results: [optional; paste findings from ImagifyConvert OG Preview] Work in the repository for this page. Inspect the code and reproduce the issue before editing. Follow its project instructions and preserve unrelated changes. 1. Identify the framework, route, metadata owner, shared layout, and any SEO plugins or file-based social images. Inspect the raw production HTML as well as the local output; a hydrated browser head or normalized checker result is not proof of correct raw tags. 2. Use GET requests to check the exact shared URL, redirect chain, final status and Content-Type, canonical, og:url, and raw og:* / twitter:* tags. Compare a social-crawler user agent when useful, without claiming it reproduces the crawler's IP, cache, or firewall treatment. 3. Check the actual og:image response and bytes: public absolute HTTPS URL, no login or expiring signature, image Content-Type, real dimensions, and readable thumbnail crop. Prefer an existing suitable JPEG/PNG asset. If a new asset is needed, report that rather than inventing an image URL. 4. Fix the root cause with the smallest change using the framework's existing metadata mechanism. Supply page-specific title, description, type, URL, image details/alt text, and summary_large_image Twitter tags where appropriate. Remove accidental duplicate tags. Keep redirects, canonical, and og:url consistent. In Next.js, account for shallow metadata merging and file-based image precedence; keep metadata exports in Server Components. 5. Check robots rules and crawler/CDN failures where evidence is available. Do not weaken authentication or expose private routes. Separate code defects from platform cache issues. If image bytes changed, use a versioned image path; do not change the page's identity just to bypass caches. 6. Run the production build and relevant lint/type checks. Inspect the generated HTML for missing/duplicate tags and verify referenced local assets and internal links. Add a focused regression check if the fix changes application behavior. 7. Report the cause, changed files, verification results, and any remaining external blockers. Give the exact Facebook Sharing Debugger or LinkedIn Post Inspector re-scrape steps when relevant. Do not claim a platform cache was refreshed or production was deployed unless verified. Leave deployment to the project's authorized release workflow. Reference guide: https://imagifyconvert.com/tools/og-preview/debugging-guide Checker: https://imagifyconvert.com/tools/og-preview
The prompt asks your agent to inspect the response, make a targeted fix, and verify the production build. This button only copies text; it does not send your project to an AI service.