Link Preview Debugger: How to Find What Broke Before You Share

A broken link preview is usually blamed on the last thing someone touched. Sometimes that is fair. More often, the preview is the messy end result of five systems making slightly different choices: your CMS, your frontend, your CDN, the social crawler, and the platform cache.

That is why "it looks fine in the browser" is not a useful debugging standard. Browsers forgive a lot. Preview crawlers tend to read the first HTML response, follow redirects, fetch a few metadata assets, and make a card from whatever was available at that moment.

Use this flow when a link preview shows the wrong image, no image, an old title, or no card at all.

Start with the final public URL

Debug the URL people will actually share, not the CMS preview link and not a staging URL that happens to look similar.

Before you inspect metadata, check the basics:

• Does the URL return a 200 response for the final destination?
• Does it redirect through more than one hop?
• Does the canonical URL match the page you expect people to share?
• Does og:url point to the same final page?
• Is the page public without cookies, geofencing, or login state?

If the URL redirects from /old-page to /new-page, the card may be built from the destination. If og:url points somewhere else again, you have made the crawler choose between three versions of the truth. That is when previews start looking haunted.

Run the URL through the link preview checker before you open five platform-specific tools. A source-of-truth scan makes the rest of the debugging less guessy.

Read the raw HTML, not the rendered page

Most preview crawlers care about metadata in the initial HTML response. They do not wait around for your React app, personalization layer, or analytics script to politely add the tags later.

View source or fetch the page HTML and look for:

1<meta property="og:title" content="..." />2<meta property="og:description" content="..." />3<meta property="og:image" content="https://example.com/preview.jpg" />4<meta property="og:url" content="https://example.com/final-page" />5<meta name="twitter:card" content="summary_large_image" />6<meta name="twitter:title" content="..." />7<meta name="twitter:description" content="..." />8<meta name="twitter:image" content="https://example.com/preview.jpg" />

If those tags are missing from source but appear in DevTools after the page has loaded, your browser is seeing a nicer version than the crawler gets.

That pattern is common after frontend refactors. The page still looks right to humans, but the card metadata moved from server-rendered HTML to client-side state. Social crawlers are not patient customers. They are closer to a quick HTTP probe with opinions.

Follow the image all the way through

When the card image is missing, the tag is only the start of the trail.

Open the og:image or twitter:image URL directly and check:

• The image returns a 200 response.
• The URL is absolute, not relative.
• The image does not require a signed cookie or short-lived token.
• The response has the expected content type.
• The file is not huge enough to time out a cautious crawler.
• The visual still makes sense after center cropping.

Large editorial images are a quiet source of preview failures. A 5000px product photo may look beautiful in a CMS, but it can be a poor preview asset if it is heavy, slow, or composed for a different crop.

For a deeper size pass, use the Open Graph image size guide. For a quick validation of tags and fetchability, use the Open Graph checker.

Separate source problems from cache problems

There are two very different situations:

Do not start cache-busting before the source is clean. It wastes time and makes the incident harder to explain later.

A good rule: if ShareScan, curl, or view-source still sees old metadata, fix the page. If the source is clean and only one social platform is wrong, you are probably dealing with cache.

If the old preview image keeps coming back after the source is fixed, use the Open Graph image refresh checklist before you change the card again. It helps you confirm whether the stale part is the page HTML, the image URL, or the platform cache.

Look for crawler blocking

Some teams accidentally block the exact traffic needed to build preview cards. It can happen through WAF rules, bot filters, robots policies, country blocks, or asset permissions that were added for good reasons somewhere else.

Check both the HTML page and the image URL. A crawler may be able to read the page but not fetch the image, which gives you a card with text and no visual.

The annoying version is an intermittent block: the first request passes, the image request fails, and the platform caches that bad first attempt. When that happens, the fix is not only "try again." You need to make the fetch path boring and repeatable.

Debug the card field by field

When several things changed in the same release, resist rewriting all metadata at once. Work through the card in order:

1. Final URL and status code
2. Canonical URL and og:url
3. og:title and twitter:title
4. og:description and twitter:description
5. og:image and twitter:image
6. Image dimensions, response headers, and fetchability
7. Platform cache state

That order keeps you from polishing the title while the crawler is still being sent to the wrong URL.

What to automate

Manual debugging is fine for one campaign page. It does not scale to product pages, blog archives, docs, or regional variants.

Automate the checks that regress quietly:

• A required metadata tag disappears.
• og:image changes to a broken or blocked URL.
• A canonical URL drifts away from og:url.
• A template starts emitting the same title across many pages.
• A deploy changes redirect behavior.
• A CMS image field becomes optional without a fallback.

The point is not to make every preview perfect forever. The point is to catch the embarrassing breakages before the link travels through Slack, LinkedIn, X, or a customer newsletter.