# Link previews: why your shared links look broken, and the fix

[Canonical HTML page](https://gradiently.design/guide/link-preview-image)

You paste your link into a chat and get a grey box, the wrong picture or a logo cropped in half. Almost every broken preview comes down to one of eight causes, and all of them are fixable in minutes.

## The short version

- A link preview image is the picture a platform shows when someone shares a URL, and it comes from the page's og:image tag.
- The most common reasons a link preview image is missing are no og:image tag, a relative image URL, an image the crawler can't reach, and tags added by JavaScript after the page loads.
- Platforms cache previews, so after fixing a page you often need a debugging tool or a changed URL before the new image appears.
- A 1200×630 image with words kept in the centre previews well on almost every platform.
- Testing a link in a private message to yourself is the quickest way to see what other people will see.

A **link preview image** comes from one line in your page's HTML: the `og:image` tag. When a platform such as WhatsApp, Slack, LinkedIn or iMessage sees a link, a crawler fetches the page, reads that tag and downloads the image. If the preview is blank or wrong, something in that chain failed: the tag is missing, the image address is relative, the crawler is blocked, or the platform is still showing an old copy from its cache.

## Why link previews break: a diagnosis table

Start with the symptom you can see. The table below covers the eight causes behind broken previews, with the usual suspects first.

| What you see | Likely cause | Fix |
| --- | --- | --- |
| No image at all | No `og:image` tag on the page | Add the tag to the page's `head` |
| No image, tag is present | Relative URL such as `/share.png` | Use the full address, starting `https://` |
| No image on some apps only | Tags inserted by JavaScript | Render the tags on the server, in the first HTML response |
| No image, URL is correct | Image behind a login, firewall or `robots.txt` rule | Make the image publicly reachable |
| Old image after a change | The platform cached the first fetch | Scrape again with a debugger or change the image URL |
| Tiny square instead of a big card | Image too small, or no large card tag for X | Use 1200×630 and add `twitter:card` set to `summary_large_image` |
| Image cut off at the sides | Words placed near the edges | Keep text in the centre of the frame |
| Image loads slowly or times out | File is several megabytes | Compress it; a few hundred kilobytes is plenty |

Work down the list. When the preview is blank, the answer is almost always in the first four rows.

## The tags a working preview needs

You need surprisingly little. A title, a description, a full image URL, the image size, and one extra line so X shows a large card instead of a thumbnail. The page's canonical URL in `og:url` helps platforms group shares of the same page.

```html
<head>
  <title>Autumn menu | Hearth Bakery</title>
  <meta property="og:type" content="website">
  <meta property="og:url" content="https://example.com/autumn">
  <meta property="og:title" content="Our autumn menu is here">
  <meta property="og:description" content="Pumpkin loaf, apple buns and spiced coffee, baked every morning.">
  <meta property="og:image" content="https://example.com/share/autumn-1200x630.png">
  <meta property="og:image:width" content="1200">
  <meta property="og:image:height" content="630">
  <meta property="og:image:alt" content="Autumn menu at Hearth Bakery">
  <meta name="twitter:card" content="summary_large_image">
</head>
```

A complete set. Note the absolute https image URL; a path like /share/autumn.png is a very common mistake.

> **View the source, not the page** Crawlers read the raw HTML your server sends and most never run JavaScript. Open your page, choose View Page Source, and search for `og:image`. If it isn't in that source, no chat app will find it, however correct it looks in your browser's inspector.

Frameworks make this easy to get wrong. A single page app that sets tags after loading will preview fine in a few places and fail in most. Use your framework's server side metadata feature instead, or generate the image per page as described in [dynamic OG images](https://gradiently.design/guide/dynamic-og-images).

## How to refresh a cached link preview

Platforms fetch a page once and keep the result for a while, so fixing your tags doesn't fix posts people already shared, and sometimes not new shares either. Use the platform's own tools where they exist, and change the URL where they don't.

1. **LinkedIn** Paste the URL into the [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/). It fetches the page again and shows exactly what LinkedIn sees.
2. **Facebook, Instagram and WhatsApp** Meta's Sharing Debugger, in its developer tools, shows the tags it found and has a button to scrape again. WhatsApp can take longer to catch up.
3. **Slack, Discord, iMessage and others** Most have no public refresh tool. Rename the image file, for example `autumn-v2.png`, and update the tag, so the crawler sees a new address.
4. **Stubborn cases** Share the page with a harmless query string such as `?v=2`. Platforms treat it as a new link and fetch it fresh.

## Designing an image that previews well everywhere

Once the tags work, the image itself decides whether anyone taps. Make it 1200×630, a wide frame of about 1.91 to 1, which every major platform accepts. Some apps show it smaller or crop a little from the sides, and a few fall back to a square, so keep the words in the centre. The full sizing story is in [OG image size](https://gradiently.design/guide/open-graph-image-size).

- Open Graph 1200×630: 1200 × 630
- LinkedIn link 1200×627: 1200 × 627
- Square fallback 1200×1200: 1200 × 1200

The 1200×630 card, LinkedIn's near identical link image, and the square some apps crop to. Centred words survive all three.

A link preview image where the headline sits over a bright area of the gradient and is hard to read

Words run straight across the brightest part of the background and vanish at thumbnail size.

The same link preview image with a darker, calmer area of the gradient behind the headline

The same card with a calm, high contrast area behind the words. Readable even in a crowded chat.

### Avoid

- Your logo alone on white
- A screenshot of the page itself
- Long sentences in small type
- Text touching the edges
- The same image for every page

### Do

- A short headline that matches the page
- A background people recognise as yours
- Type big enough to read at 300 pixels wide
- A clear margin all round
- One image per important page

A preview is tiny in a chat thread, so the rules from [thumbnail text](https://gradiently.design/guide/typography-for-thumbnails) apply: a few large words, strong contrast, one idea. In Gradiently a design's Mark keeps its calmest region behind the words and picks light or dark type per line, so the headline stays legible however the platform scales the card. Start from the Link preview size in the Studio and the same design can become your 1200×600 blog banner and the rest of your [social media image sizes](https://gradiently.design/guide/social-media-image-sizes).

## A two minute test before you share

1. View the page source and confirm `og:image` is there with a full https URL.
2. Open that image URL in a private browser window. If it doesn't load there, crawlers can't load it either.
3. Run the URL through the LinkedIn Post Inspector or Meta's debugger to see the parsed tags.
4. Send the link to yourself in WhatsApp or Slack and look at it on a phone.
5. If anything is stale, change the image file name and test again.

Do this once for each template on your site, not every page, and broken previews stop being a surprise. If you're building a site from scratch, the [website hero background](https://gradiently.design/guide/website-hero-background) guide covers the main image those previews often borrow from.

## FAQ

### Why is my link preview image not showing?

Usually the page has no og:image tag, the tag uses a relative URL, the image is blocked from crawlers, or the tags are added by JavaScript. Check the raw page source first.

### How do I update a link preview that shows an old image?

Platforms cache previews. Ask for a fresh scrape of the URL with the LinkedIn Post Inspector or Meta's Sharing Debugger, or rename the image file so its URL changes.

### What size should a link preview image be?

1200×630 pixels. Keep the words in the centre, because some apps crop the sides or show the card as a square.

### Why does X show a small thumbnail instead of a large image?

Add a `twitter:card` meta tag set to `summary_large_image`, and make sure the image is large enough, ideally 1200×630.

### Do link previews work with single page apps?

Only if the Open Graph tags are in the HTML the server sends. Most crawlers don't run JavaScript, so tags added in the browser are invisible to them.