# Bluesky link preview not showing: how link cards work and why they go blank

**In short:** On Bluesky the posting app builds the link card when you write the post: it asks Bluesky's cardyb service for the og:title, og:description and og:image, shrinks the image to a JPEG under 1 MB and stores it in the post. Fixing your page never updates posted cards. Bots and API posts get no card unless they build it themselves. Transparent PNGs turn black.

> Why a Bluesky post has no link card, no image or a black one: the posting app makes the card once and stores it in the post, from Bluesky's source.

Published 2026-11-21 · https://shareglint.com/en/guides/bluesky-link-preview-not-showing

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](https://docs.bsky.app/docs/advanced-guides/posts), the source of the official app ([bluesky-social/social-app](https://github.com/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](https://github.com/bluesky-social/atproto/blob/main/packages/api/lexicons/app/bsky/embed/external.json). 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

1. **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.
2. **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.
3. **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_1MB` and `doResize`).
4. **The app uploads it as a blob and stores the card in the post** (`app.bsky.embed.external`: `uri`, `title`, `description`, `thumb`). The lexicon caps `thumb` at 1,000,000 bytes.
5. **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):

```json
{"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`.** Set `og:title`, `og:description` and `og:image` — the three tags Bluesky's own example code reads. We could not test whether cardyb falls back to `twitter: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 with `Cache-Control: public, max-age=3600, stale-while-revalidate=86400` and images with `max-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](https://help.micro.blog/t/trouble-getting-bluesky-to-recognize-link-thumbnails/3919) 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](https://shareglint.com/en/guides/refresh-link-preview) 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:

```json
"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](https://shareglint.com/en) 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

1. Did a person post it from the official app, or a bot? Bots need to build the card.
2. Does the page have `og:title`, `og:description` and `og:image` in the HTML source? Our [OG checker](https://shareglint.com/en/tools/og-checker) shows what a crawler sees.
3. Is the image JPEG or PNG with a solid background, not SVG, reachable without cookies or referer checks?
4. 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](https://shareglint.com/en/guides/mastodon-link-preview-not-showing).

## FAQ

### Why is my link preview not showing on Bluesky?

The card is made by the app you post from, before you press Post. If Bluesky's card service could not read your page (an error, bot protection, no og tags), the composer shows no card. Posts made through the API or by bots have no card unless the bot builds one: Bluesky's docs say each client fetches and embeds the card itself.

### How do I refresh a Bluesky link preview?

You cannot change the card of a post that is already published: the title, description and image are stored in the post record. Delete and repost, or post again after the fix. Bluesky's card service sent Cache-Control max-age=3600 on its page lookups and max-age=86400 on images in our test, so a new post may still show the old data for a while; a URL with ?v=2 avoids that.

### Why is my Bluesky link card image black?

The web app re-encodes the og:image as a JPEG through a canvas without filling a background first. In our test of that code in Chrome, the transparent area of a PNG came out pure black (0, 0, 0). Use an og:image with a solid background.

### What og:image size does Bluesky need?

The post can store a card image of at most 1,000,000 bytes, and the app scales it to at most 2,000 px on the long side and re-compresses it as JPEG until it fits. 1200×630 works well. SVG is not accepted: Bluesky's image proxy answered 400 for an SVG in our test.

### Does Bluesky use twitter:image?

We could not confirm it: Bluesky's card service, cardyb, is not open source, and its tag rules are not documented. Bluesky's own example code for building cards reads og:title, og:description and og:image. Set those three.
