Bluesky does not crawl your link when people see a post. The card is made once, by the app the author posts from, and saved inside the post itself — title, description and a copy of the image. That one design decision explains most "Bluesky preview not showing" problems: posts from bots have no card, fixing your page does not fix posts already made, and whatever the app did to your image is what everyone sees.
Where this comes from. Bluesky's developer docs on website card embeds, the source of the official app (bluesky-social/social-app at 1.137.0, the latest release on 2026-11-21: src/lib/link-meta/link-meta.ts, src/lib/api/resolve.ts, src/lib/media/manip.web.ts) and the app.bsky.embed.external lexicon in bluesky-social/atproto. On 2026-11-21 we also called Bluesky's card service, cardyb.bsky.app, with public URLs (GitHub, Wikipedia, example.com) and ran the web app's image code in Chrome. We did not post to Bluesky, and the card service is not open source, so its exact rules for reading tags are not known.
How a Bluesky link card is made
- You paste a link in the composer. The app sends the URL to Bluesky's card service:
https://cardyb.bsky.app/v1/extract?url=…, with a 15-second timeout. - cardyb fetches your page and returns a title, description and image. The image comes back as a link to Bluesky's image proxy,
https://cardyb.bsky.app/v1/image?url=…, not to your server. - The app downloads that image and shrinks it: at most 2,000 px on the long side, re-encoded as JPEG at the highest quality that stays under 1,000,000 bytes (
IMAGE_SIZE_CONFIG_2K_1MBanddoResize). - The app uploads it as a blob and stores the card in the post (
app.bsky.embed.external:uri,title,description,thumb). The lexicon capsthumbat 1,000,000 bytes. - Everyone sees that stored card. Bluesky's docs: "each client fetches and embeds this card metadata, including blob upload if needed. Embedding the card content in the record ensures that it appears consistently to everyone and reduces waves of automated traffic being sent to the referenced website."
What cardyb returned for a page with good tags (github.com/mastodon/mastodon):
{"error":"","likely_type":"html","url":"https://github.com/mastodon/mastodon",
"title":"GitHub - mastodon/mastodon: Your self-hosted, globally interconnected microblogging community",
"description":"Your self-hosted, globally interconnected microblogging community - mastodon/mastodon",
"image":"https://cardyb.bsky.app/v1/image?url=https%3A%2F%2Fopengraph.githubassets.com%2F…",
"twitter_card":"summary_large_image"}
For example.com, a page with a <title> and no Open Graph tags, it returned the title and an empty image — a card with no picture. For a URL that answers 404 it returned {"error":"Unable to generate link preview", …} — no card.
Why there is no card at all
The post was made by a bot, a script or a third-party app that does not build cards. This is the most common case. A post created through the API with just text and a link facet shows a plain link. The client has to fetch the metadata, upload the image and attach the embed; Bluesky's docs show it as one short Python function. Many RSS-to-Bluesky bridges and schedulers do it, some do not.
The card service could not read your page. cardyb answered "Unable to generate link preview" for a 404. Bot protection that challenges unknown clients, a login or consent wall in front of the page, or a server that is slow for more than the composer's 15 seconds all end the same way. We do not know cardyb's user agent or IP ranges, so we cannot say which firewall rule would block it; if Cloudflare or a WAF sits in front of your site, check its logs for blocked requests at the moment someone posted.
The author removed it. The composer shows the card with a remove button; a removed card is not saved.
Why the card has no image or a wrong one
- No
og:image. Setog:title,og:descriptionandog:image— the three tags Bluesky's own example code reads. We could not test whether cardyb falls back totwitter:image. - An SVG. Bluesky's image proxy answered
400 {"error":"Unable to serve image from URL"}for an SVG on Wikimedia. A WebP came through as WebP and was then converted by the app. - A transparent PNG comes out black. The web app draws your image on a canvas and saves it as JPEG with no background fill. We ran that code on a 1200×630 PNG with a transparent background and a grey square: the square kept its colour (51, 51, 51) and the transparent corner became pure black (0, 0, 0). A dark logo on a transparent background disappears. Give the image a solid background. (We tested the web code path; the iOS and Android apps resize with a different library.)
- A huge image is softened. Anything over 2,000 px is scaled down, and a detailed image may need a low JPEG quality to fit under 1 MB. A 1200×630 image is not scaled, only re-encoded.
- The image host refuses the proxy. The image is fetched by
cardyb.bsky.app, not by the reader's browser, so hotlink protection that requires your own site as referer, or an image URL that needs cookies, gives an empty image.
Refreshing a Bluesky card
A published post keeps its card. There is no debugger and no cache to clear, because the card is part of the post record. Your options:
- Delete and repost after fixing the page, or post again.
- Use a new URL variant for the new post (
?v=2). On 2026-11-21 cardyb answered page lookups withCache-Control: public, max-age=3600, stale-while-revalidate=86400and images withmax-age=86400, stale-while-revalidate=604800, so a repost of the same URL soon after a fix can still get the old title or image. A Micro.blog help thread describes the same: links already used on Bluesky kept their old data. - Give a changed image a new file name, so no cache in between can return the old one.
Refreshing link previews covers the other platforms.
If you post from code
Build the card yourself, the way the docs show: fetch the page, read og:title, og:description and og:image, download the image, upload it with com.atproto.repo.uploadBlob and attach it:
"embed": {
"$type": "app.bsky.embed.external",
"external": {
"uri": "https://example.com/post",
"title": "Post title",
"description": "One-line summary",
"thumb": { "$type": "blob", "ref": { "$link": "bafkrei…" }, "mimeType": "image/jpeg", "size": 23527 }
}
}
Keep the uploaded image under 1,000,000 bytes, as JPEG or PNG, and resolve a relative og:image against the page URL. If you post many links a day, you can also render one card image per post yourself instead of fetching the page's: Shareglint returns a 1200×630 PNG or JPEG for a template and a title, which fits Bluesky's limit and works as the page's og:image everywhere else.
Checklist
- Did a person post it from the official app, or a bot? Bots need to build the card.
- Does the page have
og:title,og:descriptionandog:imagein the HTML source? Our OG checker shows what a crawler sees. - Is the image JPEG or PNG with a solid background, not SVG, reachable without cookies or referer checks?
- Fixed it? Old posts keep the old card; post again, ideally with a new URL variant.
Mastodon works the opposite way — every server fetches the page itself and keeps its own card for two weeks: Mastodon link preview not showing.