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
- 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. - 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.
- 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. - It fetches the page with
Accept: text/htmland the user agentMastodon/4.7.6 (http.rb/…; +https://<server>/) Bot, follows redirects, and keeps the response only if the status is 200 and the content type istext/html. It reads at most about 1 MB of HTML. Timeouts: 5 s to connect, 10 s per read, 30 s in total. - It tries oEmbed first (a
<link type="application/json+oembed">in the page), then Open Graph. - 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.
- A failed fetch is not retried (
LinkCrawlWorkerruns withretry: 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:imageis not used. A page that relies ontwitter:imagewith noog:imagegets a card with no picture on Mastodon. Setog:image.- A relative
og:imageworks 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 checksmime_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:imageinstead ofog: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
curlthe page with a Mastodon-like user agent: 200 andtext/html?og:titleandog:imagepresent in the HTML source, not added by JavaScript? Our OG checker shows what a crawler sees.og:imageis JPEG, PNG, GIF or WebP, under 8 MB, and downloadable without cookies?- The post has no image or quote attached?
- 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.