Menu
Sign up

Mastodon link preview not showing: how preview cards are built, from Mastodon's source

Why a Mastodon post has no link card or no image, from Mastodon 4.7.6's source: the 200 + text/html rule, og:image only, 8 MB, the two-week cache.

Published November 21, 2026 · 2 min read

On Mastodon there is no single crawler that builds your link preview. Every server builds its own: the author's server when the post is published, then each server that receives the post. A link that previews fine on mastodon.social can show a bare link on a smaller server, and a fix to your page may never show up on a post that already went out. This page explains how the card is built and which rules leave it empty or without an image.

Where this comes from. Everything below is read from Mastodon's source code at release v4.7.6 (the latest release on 2026-11-21): fetch_link_card_service.rb, link_details_extractor.rb, preview_card.rb, request.rb and activitypub/activity/create.rb. We did not run a Mastodon server or post test links, so nothing here is a measurement; servers on older versions, and forks such as Glitch or Hometown, can behave differently.

How a Mastodon server builds a card

  1. Someone posts a link. The author's server queues a fetch at once (PostStatusService → LinkCrawlWorker). Each server that receives the post queues its own, after a random delay of up to one minute (DISTRIBUTE_DELAY = 1.minute, "to avoid DDoSing the link"). A popular post therefore sends one request per receiving server to your page.
  2. No card for some posts. The service returns early if the post already has a card, has media attached (images, video, audio) or quotes another post.
  3. It reuses a stored card. Cards are stored per URL. A new fetch happens only if the server has no card for that URL, the card is more than two weeks old (updated_at <= 2.weeks.ago), or the card has no image.
  4. It fetches the page with Accept: text/html and the user agent Mastodon/4.7.6 (http.rb/…; +https://<server>/) Bot, follows redirects, and keeps the response only if the status is 200 and the content type is text/html. It reads at most about 1 MB of HTML. Timeouts: 5 s to connect, 10 s per read, 30 s in total.
  5. It tries oEmbed first (a <link type="application/json+oembed"> in the page), then Open Graph.
  6. It reads the tags and saves the card. If the image cannot be downloaded or is not accepted, the card is saved without the image. If there is no title, no card is saved at all.
  7. A failed fetch is not retried (LinkCrawlWorker runs with retry: 0).

Which tags Mastodon reads

From LinkDetailsExtractor:

Card field Read from, in order
Title (required) JSON-LD headline → og:title → <title>
Description JSON-LD description → og:description → <meta name="description">
Image og:image only
Image alt text og:image:alt
URL the card is stored under <link rel="canonical"> → og:url, same host only; otherwise the posted URL
Site name JSON-LD publisher name → og:site_name
Author name JSON-LD author → og:author / og:author:username
Author's fediverse account <meta name="fediverse:creator" content="@you@example.social">
Video player twitter:player, twitter:player:width, twitter:player:height

Two differences from other platforms are worth knowing:

  • twitter:image is not used. A page that relies on twitter:image with no og:image gets a card with no picture on Mastodon. Set og:image.
  • A relative og:image works here. The extractor joins it with the page URL (@original_url + Addressable::URI.parse(str)). Facebook and X do not do that, so keep it absolute anyway.

Tags are looked up anywhere in the document, but only the first ~1 MB of HTML is read: tags injected late in a huge page, or added by JavaScript after load, are not seen. Mastodon does not run JavaScript.

Why the card is missing

Your server did not answer 200 with text/html. The common ways to fail step 4:

  • Bot protection (Cloudflare's challenge, a WAF rule) answering 403 or 503 to a request with "Bot" in the user agent.
  • A redirect to a login, consent or cookie wall that ends at a page without your tags, or with another status.
  • A content type of application/xhtml+xml, or a missing one: the service checks mime_type == 'text/html'.
  • A slow page: more than 30 s in total, or 10 s without data.

You can check what a server would get with curl:

curl -s -o /dev/null -w "%{http_code} %{content_type}\n" \
  -A "Mastodon/4.7.6 (http.rb/5.2.0; +https://mastodon.example/) Bot" \
  -H "Accept: text/html" -L https://example.com/post
# expect: 200 text/html; charset=utf-8

(The http.rb part of the string is the HTTP library's version and varies by server; rules that match "Mastodon" or "Bot" are what matters.)

No title. A page with neither JSON-LD headline, og:title nor <title> gets no card.

The post has media or a quote. Attach an image to a post and the link in it gets no card, by design.

The first fetch failed and the URL was cached. With retry: 0, a fetch that hit a timeout or a 5xx is simply dropped for that post. If an earlier post stored a card without an image, the server tries again the next time the URL is posted (missing_image?); a card that is merely outdated waits two weeks.

Why the card has no image

From PreviewCard and its Attachmentable concern:

  • Formats: image/jpeg, image/png, image/gif, image/webp. AVIF and SVG are not accepted.
  • File size: under 8 MB (LIMIT = 8.megabytes).
  • Pixel area: any image over 33,177,600 pixels (7680×4320) is rejected; a GIF over 921,600 pixels (1280×720) is rejected.
  • The image URL must work for the server: the same bot protection and hotlink rules as the page apply to the image request.
  • twitter:image instead of og:image, as above.

A failed image does not fail the card: save_with_optional_image! saves the card without it. That is why a Mastodon card shows a title and description with an empty image area, or no image area at all.

A 1200×630 JPEG under 600 KB satisfies Mastodon and every other major platform; og:image formats by platform has the per-platform lists.

Refreshing a card

There is no debugger to clear a Mastodon card, and there cannot be one: each server keeps its own copy.

  • Posts that already have a card keep it. Editing the post does not re-fetch it unless the link changes.
  • A server re-fetches a URL only when its stored card is over two weeks old or has no image, and only when the URL is posted again.
  • To get a fresh card now, post a URL the servers have not seen: add a query string such as ?v=2. Give a changed image a new file name too, so caches in front of it do not serve the old one.

Refreshing link previews covers the other platforms' caches.

Credit on Mastodon: fediverse:creator

Add your account to articles and Mastodon shows "More from @you" under the card:

<meta name="fediverse:creator" content="@you@example.social">

In 4.7.6 the server resolves the account and credits it only if your domain is listed in that account's Author attribution settings ("add the domain name of the publication in the field below", in Mastodon's own words). Without that, the tag alone does nothing.

Checklist

  1. curl the page with a Mastodon-like user agent: 200 and text/html?
  2. og:title and og:image present in the HTML source, not added by JavaScript? Our OG checker shows what a crawler sees.
  3. og:image is JPEG, PNG, GIF or WebP, under 8 MB, and downloadable without cookies?
  4. The post has no image or quote attached?
  5. Testing a fix? Post a new URL variant; old posts keep their old card.

If the image itself is the problem — no image, the wrong size, a different one per post — Shareglint renders an og:image per page from a template, as a 1200×630 PNG or JPEG that works on Mastodon and the other platforms. Bluesky builds cards differently again: Bluesky link preview not showing.

FAQ

Why is my link preview not showing on Mastodon?

The server could not build a card from your page. In Mastodon 4.7.6 it needs an HTTP 200 with Content-Type text/html (a bot-protection 403 or a redirect to a login page fails), a title from og:title, JSON-LD or the title tag, and an og:image it can download. Posts that already have an image, a video or a quote get no card at all.

Does Mastodon use twitter:image?

No. Mastodon's LinkDetailsExtractor reads the image only from og:image. A page with twitter:image and no og:image gets a card without a picture. It does read twitter:player for video embeds.

How do I refresh a Mastodon link preview?

You cannot refresh it from outside. Each server stores one card per URL and fetches it again only when the card is over two weeks old or has no image, and only when someone posts that URL again. Posts that already carry a card keep it. To get a new card sooner, post a URL the server has not seen, for example with ?v=2.

Why does the preview show on one Mastodon server and not another?

Every server fetches the page itself: the author's server when the post is written, and each receiving server within a random delay of up to one minute. A server that was rate-limited or blocked by your site, timed out, or runs another Mastodon version can end up without a card, and a failed fetch is not retried.

What image size does Mastodon need for link previews?

Mastodon 4.7.6 accepts JPEG, PNG, GIF or WebP under 8 MB, and rejects GIFs larger than 1280×720 pixels in area and any image over 7680×4320. If the image fails, the card is saved without it. 1200×630 JPEG works on Mastodon and on the other platforms.