Troubleshooting guide

X link preview not showing?

X, formerly Twitter, calls a link preview a card. When a post includes your link, X fetches the page and reads its twitter:card tag, falling back to Open Graph for the rest. Here’s what to check, based on X’s own card documentation.

The check opens on the X preview and flags missing tags and small images. Its generated code includes twitter:card.

What X needs

Tags: twitter:card, plus og:title, og:description and og:image
Image: 2:1, from 300×157 to 4096×4096, under 5 MB. JPG, PNG, WebP or GIF, not SVG
HTML: Page response under 2 MB
Crawler: Twitterbot/1.0, follows robots.txt

From X’s card docs (archived) ↗

Common causes and fixes

1
twitter:card is missing

It’s the one tag X requires, and the only one without an Open Graph equivalent. Without it the link can show no card or only a small one.

Fix: Add <meta name="twitter:card" content="summary_large_image"> for the large image card.
2
robots.txt blocks Twitterbot

Unlike most link preview crawlers, Twitterbot follows robots.txt. A rule that blocks it, or a blanket Disallow: / for all bots, stops the card from loading.

Fix: Allow Twitterbot in robots.txt with User-agent: Twitterbot and an empty Disallow:.
3
The image doesn’t meet X’s rules

The large card needs an image of at least 300×157, at most 4096×4096 and under 5 MB. SVG isn’t supported, and only the first frame of a GIF is used.

Fix: Use a 1200×630 JPG or PNG. The OG image generator makes one in your browser.
4
X can’t download the page or the image

Firewalls, bot protection and staging passwords can block X’s servers, and the image has to be public. X gives up on page responses over 2 MB and on slow servers.

Fix: Let Twitterbot through your bot protection, keep the HTML under 2 MB, and open the image address in a private window to confirm it’s public.
5
The tags are added by JavaScript

X reads the HTML your server sends. Tags a JavaScript framework adds after the page loads are never seen.

Fix: Check your page to see which tags the server sends, then copy the generated code into your <head>.
6
X is showing an old version

X fetches a card again roughly every seven days, and caches images by their address separately.

Fix: Post the link with a query string such as ?v=2, and add one to the image address too if the picture is stale.

Still seeing the old preview?

X has no tool to refresh a card anymore; its Card Validator stopped showing previews. X fetches the page again roughly every seven days. To test sooner, post the link with ?v=2, and change the image address, for example og-image.jpg?v=2, if the picture stays old.

Send this instead

example.com/page?v=2

Next fix, next number: ?v=3

Questions

What people ask when the fixes above don’t explain it.

Do I need twitter:title, twitter:description and twitter:image?

No. X falls back to og:title, og:description and og:image when the Twitter versions are missing. Only twitter:card has no Open Graph equivalent.

Why doesn’t X show my description?

X’s apps don’t show the description at all, and the large card shows the image with the title and your domain. Make the title and image carry the message.

Why is my image cropped?

The large card is close to 2:1, slightly wider than the usual 1.91:1. A 1200×630 image loses a few pixels at the top and bottom, so keep text away from the edges.

Why does the card show in the post but not in the timeline?

X sometimes shows cards only when a post is opened. That’s X’s choice for the timeline, not a problem with your page.