Why link previews break, and how to debug the metadata

A preview is a second way to read your page

A visitor can see a perfectly good page while a shared link shows the wrong title or an empty image. The page body and the metadata used to build a preview are different inputs. Debugging becomes easier when you inspect them separately.

Open Graph defines four basic properties: title, type, image and URL. The description is optional and useful for explaining the page. These tags live in the document head; they do not automatically inherit the heading and picture shown in the body.

<meta property="og:title" content="A practical guide" />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://example.com/guide" />
<meta property="og:image" content="https://example.com/guide.jpg" />
<meta property="og:description" content="What the reader will learn." />

Sources: Open Graph protocol

Inspect the response that the reader receives

Start with the HTML delivered by the server. Check the requested URL, redirects, response status and document head. A tool that only reads server-delivered HTML will not see metadata added later by client-side JavaScript.

For each important page, use a specific title, description and image rather than copying the homepage defaults. Confirm that the image URL actually returns an image and that access does not depend on a signed-in session. Use an absolute URL to make the intended resource unambiguous.

Build a useful fallback

A bookmark collection will encounter pages that supply only part of the metadata. Decide your fallback order: for example, Open Graph title, then the HTML title, then the hostname. Keep absent descriptions absent rather than inventing a summary that appears to come from the publisher.

A preview card can still work without a picture. Reserve a predictable image area, use a quiet placeholder and show the source domain. Truncate long text visually without changing the stored original, so the same record can be reused in a detail view.

For batch inspection, the Link Preview API guide shows how our Actor accepts URLs and returns available metadata. It does not render client-side JavaScript, which is a useful limit to understand before choosing it for a particular site.

Treat URLs and metadata as untrusted input

If you build your own server-side fetcher, arbitrary URL input creates an SSRF risk: a request can target internal resources rather than a public page. Validate the protocol and destination, handle DNS resolution carefully and apply the same checks to redirects. Add response-size and timeout limits.

Render extracted titles and descriptions as text. They are publisher-controlled content, not trusted markup. Keep fetching, extracting and displaying as distinct steps so each has clear limits and can be tested independently.

Sources: OWASP SSRF prevention guidance

Keep your own cache observable

If you cache preview records, store the fetched time and the source URL with each result. Define a refresh policy so a failed request does not permanently replace a previously useful card. A small test set should include redirects, missing tags, broken images and an unusually long title.

When a preview differs from the page, compare the latest server response with your saved record before changing the design. You may be looking at a stale cache rather than a missing tag. The goal is a card that represents the source clearly and fails gracefully.