How to Fix BlueSky Link Card Preview Errors

A weak link card can make a good BlueSky post look unfinished. The post text may be fine, but the preview image is missing, the title is wrong, or the card never appears at all.

The fix usually starts on the linked page, not inside the post. BlueSky external cards depend on link metadata such as title, description, image, URL access, and how the page responds when fetched.

BlueSky's post documentation explains external embeds and website card records.

How BlueSky link cards work

A BlueSky post can include an external embed. That embed stores the URL, title, description, and an optional thumbnail blob. In a normal composer flow, the app fetches the page, reads metadata, uploads or references a thumbnail, and attaches the card to the post record.

That means a pasted URL is not only text. It becomes a card only if the page can be fetched and parsed into a usable external embed.

Common reasons a BlueSky card does not show

Missing og:title, og:description, or og:image tags.

An image URL that blocks crawlers, redirects strangely, or returns the wrong content type.

A social image that is too large, too small, or in a format the client does not handle well.

A page that requires JavaScript before metadata appears.

A private, blocked, rate-limited, or geofenced page.

A stale cached preview from an earlier version of the page.

Check the Open Graph basics first

Open the page source and confirm the page has a clean title, description, canonical URL, and image. The image should be reachable from a logged-out browser session and should return a normal image response.

Use an absolute https URL for og:image.

Keep the card image stable before sharing the link widely.

Avoid images behind cookies, hotlink protection, or redirects.

Make sure the title and description describe the page, not the site homepage.

Update the canonical URL if the page moved.

If the problem is not the metadata itself, check the companion guide on resolving precise image aspect ratios and automated container cropping boundaries before rebuilding the launch card.

If the card is fine but the published reply branch is missing, use the guide on resolving network sync delay and missing post visibility anomalies inside public relays before creating duplicate launch replies.

What to do if the card is stale

If the card uses old metadata, change the page metadata first and wait for the preview path to fetch the new version. Some clients and services cache link metadata. A changed URL with a real cache-busting query parameter can help during testing, but do not create many duplicate public URLs just to force a preview refresh.

The cleaner long-term fix is stable metadata before the link is scheduled. Do not wait until launch minute to find out the card title still says 'Untitled'.

How ONYX helps before scheduling

ONYX's composer includes link preview handling so you can see whether a URL looks clean before the post goes into the queue. That does not override BlueSky's final rendering rules, but it gives you a practical checkpoint before approved posts publish.

Use the free BlueSky line break formatter to clean the post text around the link before scheduling.

A safe link-card troubleshooting checklist

Paste the URL into a post draft before scheduling.

Confirm the title, description, and image are the ones you expect.

Check the page's Open Graph tags if the card is missing.

Fix metadata at the source page rather than rewriting the post repeatedly.

Schedule the approved version only after the preview looks acceptable.

A good BlueSky card does not save a bad post, but a broken card can weaken a good one. Treat link previews as part of the publishing checklist, especially for launches, newsletters, product updates, webcomic pages, and public-sector announcements.

Schedule reviewed BlueSky link posts with ONYX after the preview and formatting pass.