Bluesky Link Preview Not Showing? Causes and Fixes

On Bluesky, the app that creates a post has to attach the link preview: Bluesky’s documentation describes no step that adds one from a URL in your text. Bluesky’s developer documentation, checked October 12, 2026, says “each client fetches and embeds this card metadata, including blob upload if needed”. So a post that shows a bare URL was created without a link card, because the tool does not build one, it could not read the page, or the post already carried an image or a video.

How a Bluesky link preview is made#

Bluesky’s docs call the preview a “website card embed”. This post calls it a link card. It is an embed inside the post record, one of the “external embeds (like link/webpage cards, which is the preview that shows up when you post a URL)” (Posts in-depth).

The client is whatever creates the post: the Bluesky app, a scheduler, an automation module or a script. That client has to fetch your page and put the card into the record when it creates the post. A post with a card looks like this:

{
  "$type": "app.bsky.feed.post",
  "text": "post which embeds an external URL as a card",
  "createdAt": "2023-08-07T05:46:14.423045Z",
  "embed": {
    "$type": "app.bsky.embed.external",
    "external": {
      "uri": "https://bsky.app",
      "title": "Bluesky Social",
      "description": "See what's next.",
      "thumb": {
        "$type": "blob",
        "ref": {
          "$link": "bafkreiash5eihfku2jg4skhyh5kes7j5d5fd6xxloaytdywcvb3r3zrzhu"
        },
        "mimeType": "image/png",
        "size": 23527
      }
    }
  }
}

Bluesky documents two special cases: an “enhanced preview card” for articles with a Standard.site record, and an inline player for Bandcamp releases (App integrations). Whether either works on a post created without a card is not documented.

What a link card holds#

According to Bluesky’s schema for the embed, the embed has these fields:

Why your Bluesky link preview is not showing: a checklist#

The list is ordered by what is cheapest to check first. It comes from Bluesky’s documentation, not from support cases.

Check the post itself#

A post’s record is public: Bluesky’s schema for com.atproto.repo.getRecord says “Get a single record from a repository. Does not require auth.” The request takes a repo (the handle), a collection and an rkey. Bluesky’s cookbook script takes the rkey from the last part of a bsky.app post URL. On bsky.social, the host Bluesky lists as its “Entryway” (API Hosts and Auth), which forwards most requests to the account’s own server (PDS Entryway), the address has this shape:

https://bsky.social/xrpc/com.atproto.repo.getRecord?repo=<handle>&collection=app.bsky.feed.post&rkey=<last part of the post URL>

No embed in the JSON means no card was attached. An embed whose $type is app.bsky.embed.external is the card. Accounts that Bluesky does not host use their own server’s address.

Links show as text on Bluesky? That is a different problem#

A URL that is not clickable is a separate fault. A clickable link is a “facet” on the text, and the preview is an embed. Bluesky’s rich text docs say “Clients to Bluesky should produce facets using parsers”, so the tool has to add them. A URL sent without a link facet is plain text: the docs say this outright for mentions (“It will be rendered as text in the post instead of a link”, Posts in-depth) and describe links as the same kind of annotation.

In a script, use the SDK’s helper. According to Creating a post, the TypeScript example calls rt.detectFacets(client), the Python example builds links with TextBuilder, and “The Go SDK does not ship a high-level rich-text builder.” If you build facets by hand, the rich text docs say “Facet ranges are indexed using byte offsets into the UTF-8 encoding.”

How to check a page’s Open Graph tags#

Bluesky’s example code reads og:title, og:description and og:image (Posts in-depth). It is example code for a client: which tags the Bluesky app itself reads, and whether it falls back to Twitter card tags or the page title, is not documented. The Open Graph protocol requires og:title, og:type, og:image and og:url, and lists og:description as optional.

View the page’s source and search for og:, or run this from a terminal:

curl -sL https://example.com/your-page | grep -i 'og:'

• Put the tags in the HTML the server sends: Bluesky’s example does one plain HTTP GET. Whether any fetcher runs JavaScript first is not documented.
• The og:image value should be a full https:// URL that opens by itself in a private window.

Bluesky documents no preview checker: none appears in its developer docs, its User FAQ or its Support page, which gives an email address and no help articles. For Buffer users, Buffer’s troubleshooting page suggests “the Facebook Sharing Debugger or Buffer’s scraper debugging tool”. Those show what their own fetchers see, not what the Bluesky app sees.

How to fix it, by how you post#

In the Bluesky app#

How the app’s composer offers, adds or removes a card is not documented. If no preview shows there for a link, work through rows 3 to 5 of the checklist.

For row 4, add the link to a post in the app while watching your server or CDN logs, and allow the request that gets blocked at that moment. Bluesky documents no user agent to match in advance.

From a scheduler#

A scheduler is the client for the posts it creates, so find out whether it builds the card: search its documentation for “Bluesky” next to “link preview” or “link card”.

Buffer documents it today: its help center says “For Bluesky, link previews are fully customizable”, and its API guide lists Bluesky among the networks that support its linkAttachment field. The table on the same help page shows a dash under “Link preview” for Bluesky, so that page disagrees with itself. Buffer fetches your page with its own bot, and when a site blocks it, “Buffer will need to be explicitly allowed” (troubleshooting page). The bot page gives its user agent.

Make’s documentation for its Bluesky app, read on October 12, 2026, lists a “Create a post” module and says nothing about link cards or embeds: not documented.

From a script, an automation or an agent#

Build the embed yourself: fetch the page, read its tags, upload the image with com.atproto.repo.uploadBlob, and put an app.bsky.embed.external object in the post’s embed field. Bluesky’s docs give code in Python, TypeScript and Go (Posts in-depth, Creating a post). Add link facets too.

Bluesky’s cookbook has a script that does this, create_bsky_post.py (README), with an --embed-url option (script). It was not run for this post. Bluesky’s docs add: “For a real application, reach for one of the SDKs listed at atproto.com/sdks rather than writing the raw requests by hand.”

An AI agent that posts through a tool or an API is in the same position: the tool it calls has to attach the card. If your posts come from a feed, see auto-posting an RSS feed to Bluesky.

Planning posts ahead of time? See how far ahead each network lets you schedule.

Frequently asked questions#

Why do my links show as plain text on Bluesky when I post from a tool?#

The tool sent the URL without a link facet: see Links show as text on Bluesky.

The Bluesky app shows a preview when I paste a link. Why doesn’t my scheduler or automation?#

The app and your tool are separate clients, and each has to attach its own card (Bluesky docs): see how to fix it, by how you post.

Does Bluesky use og:image, or Twitter card tags?#

Which tags the Bluesky app reads is not documented: see the tag check. Other tools decide for themselves: Buffer says its scraper checks Open Graph and Twitter Card image tags (troubleshooting page). Set the Open Graph tags.

How do I allow Bluesky’s link preview fetcher through my firewall?#

Bluesky documents no user agent or IP range for the app’s fetcher: its developer docs, User FAQ and Support page name none. For a post written in the app, use the log check. A scheduler that builds the card fetches your page itself, so its fetcher is the one to allow. Buffer documents its bot’s user agent (bot page).

Can a Bluesky post have both an image and a link preview?#

No. A post has one embed field (post schema), so you choose the card or the media, as in row 2 of the checklist. A quote post can sit next to a card (record with media schema).