OG image not showing? A checklist to fix your link preview

OG image not showing on a shared link? The cause is nearly always one of five things: the og:image address is relative, the tag is added by JavaScript after the page loads, the crawler cannot fetch the image, the file breaks a platform's limits, or the platform is still showing a cached preview. Check them in that order. Each step below takes a minute and rules one cause out for good.

Step 1: use an absolute https URL

A crawler reading your page has no idea where /og.png lives. It needs the whole address, protocol and domain included. Relative paths, protocol-relative paths (//example.com/og.png) and plain http:// addresses are the most common reason a preview comes up blank.

<!-- Broken: the crawler cannot resolve these -->
<meta property="og:image" content="/og/launch.png" />
<meta property="og:image" content="//example.com/og/launch.png" />

<!-- Working: full https URL, size and alt declared -->
<meta property="og:image" content="https://example.com/og/launch-v2.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="Launch week, on a deep violet background" />
<meta name="twitter:card" content="summary_large_image" />

Declaring the width and height matters on the first share: Facebook says that without them, a page may appear without its image until the crawler has fetched it once. Open Graph tags covers the rest of the set.

Step 2: make sure og:image is in the server HTML

Your browser's inspector shows the page after JavaScript has run, so a tag can look perfect there and still be invisible to crawlers. Single page apps that set meta tags in the browser (with a client-side head manager, for example) are the classic case. Check what a crawler actually receives:

# The HTML a crawler receives: is og:image in it?
curl -s -A "facebookexternalhit/1.1" https://example.com/launch | grep -i 'og:image'

# The image itself: expect HTTP 200 and an image content type
curl -sI https://example.com/og/launch-v2.png | grep -iE '^HTTP|content-type|content-length'

In Next.js with the App Router, set the tags in metadata so they are rendered on the server. Put metadataBase in the root layout so relative image paths become full URLs, and point it at your production domain, not localhost or a preview deployment.

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  metadataBase: new URL('https://example.com'),
  openGraph: {
    images: [{ url: '/og/launch-v2.png', width: 1200, height: 630, alt: 'Launch week' }],
  },
  twitter: {
    card: 'summary_large_image',
  },
}

Step 3: check the image is reachable by crawlers

The page loading is not enough: the crawler then makes a second request for the image, and that request can fail on its own. Open the image URL in a private window, then work through this list.

1. 1

   No login, no cookie wall

   The image must load for a stranger. Images behind auth, a staging password or a consent screen come back as an HTML page, not a picture.

2. 2

   Status 200, no redirect chains

   A 404, a 403 from a firewall or bot protection, or a redirect to a login page all end in a blank preview. One clean redirect is usually fine; several are not.

3. 3

   robots.txt allows the bots

   X's crawler identifies as Twitterbot and follows robots.txt, and LinkedIn names a blocked crawler as a common cause. A blanket Disallow on /images/ or /_next/ can block the preview.

4. 4

   A real image content type

   The server should send Content-Type: image/png or image/jpeg. A file served as text/html or application/octet-stream is often ignored. See Content-Type on MDN.

5. 5

   PNG or JPEG, not SVG

   Crawlers broadly do not render SVG previews. Use PNG for designed cards and JPEG for photos; PNG vs JPEG explains the trade.

Step 4: stay inside size and file weight limits

An image that is too small gets demoted to a thumbnail, and one that is too heavy may not be fetched at all. These are the limits the platforms publish themselves. Where a platform publishes no number, keep the file light and test.

A designed 1200×630 card with flat colour and type rarely needs to be large. Compressing it helps the apps without published limits, where heavy images are a common reason a preview quietly fails. Image compression shows how to cut weight without banding.

Step 5: clear each platform's cache

If the old picture keeps showing, the platform cached it. Facebook says it caches images by URL, so the same address will keep serving the old image even after you replace the file. The reliable fix everywhere is a new filename for the new image, then a refresh where the platform offers one.

Hashed filenames from your build tool or a version suffix (launch-v2.png) do this automatically. A query string such as ?v=2 on the image URL also works for most crawlers, but a new path is the safer bet.

A preview worth fixing

Once the plumbing works, the image still has to earn the click at thumbnail size: a short line, large type and the key words in the centre, where square crops keep them. OG image size covers the layout, and link preview image the design side. If you make a fresh image per post, dynamic OG images generates them from the title.

In Gradiently, Link preview (Open Graph) 1200×630 is a built-in size and exports as PNG, so the file arrives at the right dimensions. Export each new version under a new filename and the cache problem never starts. The same steps apply to a repository card; see GitHub social preview.