Mastodon Link Preview Not Generating: Fix Steps

When you share a link in a Mastodon post, the platform usually fetches metadata from the target page and displays a preview card with a title, description, and image. If that preview card does not appear, the post looks incomplete and can reduce engagement from followers. This problem typically occurs because the shared URL does not contain the required Open Graph tags, the Mastodon server cache has stale data, or the instance blocks external link previews. This article explains the root causes of missing link previews and provides step-by-step fixes for both the person sharing the link and the Mastodon instance administrator.

Why Mastodon Fails to Generate a Link Preview

Mastodon generates a link preview by sending a background HTTP request to the URL you paste into the compose box. The server reads the HTML of the target page and looks for specific meta tags defined by the Open Graph protocol. These tags include og:title, og:description, og:image, and og:url. If the target page does not include these tags, Mastodon falls back to the HTML title tag and a generic description. If even the fallback data is missing or the server cannot reach the URL, no preview card appears.

The second common cause is server-side caching. Once Mastodon fetches a preview for a URL, it caches that result. If the source page later changes its metadata, the old preview remains until the cache expires or is manually cleared. The default cache lifetime is 24 hours for successful fetches and longer for failed fetches.

The third cause relates to instance policies. Some Mastodon instance administrators disable link previews entirely to reduce server load or to protect user privacy. In that case, no URL will generate a preview card, regardless of the source page content.

Steps to Fix Link Previews for Your Own Posts

1. Verify the URL is correct and reachable
   Type or paste the full URL into a browser and confirm it loads without redirects or errors. Mastodon will not follow JavaScript redirects or pages that require authentication.
2. Check the source page for Open Graph tags
   Open the page source in your browser by pressing Ctrl+U on Windows or Cmd+U on macOS. Search for og:title. If you find a line like <meta property="og:title" content="Your Page Title" />, the tags exist. If they are missing, the page author must add them.
3. Use a URL shortener as a workaround
   If you cannot edit the source page, paste the URL into a service like TinyURL or Bitly. Mastodon will fetch the preview from the shortener domain, which usually includes proper Open Graph tags. This is a temporary fix.
4. Force Mastodon to refetch the URL
   In the Mastodon web interface, delete the URL from the compose box and paste it again. Wait 10 seconds. If no preview appears, the cache still holds the old data. For a fresh fetch, append a query parameter that does not affect the page, such as ?refresh=1. Example: https://example.com/page?refresh=1.
5. Test with a known good URL
   Paste a URL from a major news site like https://www.bbc.com/news. If that URL generates a preview, the problem is with the original URL. If not, the issue is on the Mastodon instance side.

Administrator Steps to Restore Link Previews

If multiple users on your instance report missing previews for various URLs, the problem likely originates from the server configuration or cache. The following steps require shell access to the Mastodon server and familiarity with the Rails console.

1. Check the link preview setting in the admin panel
   Log in as an admin. Go to Preferences > Administration > Server Settings > Content retention. Ensure the option “Enable link previews” is checked. If it is unchecked, check it and click Save.
2. Flush the preview card cache via Rails console
   SSH into your server. Run cd /home/mastodon/live then RAILS_ENV=production bundle exec rails c. In the console, enter PreviewCard.where.not(url: nil).delete_all. This removes all cached preview cards. Exit with exit. Mastodon will refetch previews on the next post containing a URL.
3. Verify the sidekiq worker is running
   Link preview fetching is handled by the LinkCrawlWorker sidekiq queue. Run sudo systemctl status mastodon-sidekiq. If the service is inactive, restart it with sudo systemctl restart mastodon-sidekiq.
4. Check the instance firewall and DNS
   Mastodon must be able to make outbound HTTPS requests. Run curl -I https://example.com from the server. If the command times out, the server cannot reach external URLs. Update the firewall rules to allow outbound traffic on port 443.

If Link Previews Still Do Not Appear

Preview card shows only the domain name with no image

This happens when the source page has og:title but lacks og:image or uses an image that is too small. Mastodon requires the image to be at least 200 by 200 pixels. The page author must add a larger og:image tag.

Preview appears on the web interface but not in apps

Some third-party Mastodon apps do not render preview cards. Test the same post in the official Mastodon web interface. If the preview appears there, the app is the limiting factor. Update the app or contact its developer.

Preview card shows outdated information

The Mastodon server cached the preview before the source page updated its metadata. The administrator must flush the cache as described in the previous section. For a single URL, the user can append a query parameter to force a new fetch.

Mastodon Link Preview vs Twitter Card Preview

Item	Mastodon Link Preview	Twitter Card Preview
Metadata format	Open Graph (og: tags)	Twitter Card (twitter: tags)
Fallback behavior	Uses HTML title tag and meta description	Uses HTML title tag and meta description
Image size requirement	Minimum 200×200 pixels	Minimum 120×120 pixels
Cache duration	24 hours for successful fetches	7 days for successful fetches
Admin control	Can disable previews or flush cache	No direct admin control on third-party

Mastodon relies exclusively on Open Graph tags, while Twitter also supports its own card tags. If a page targets only Twitter card tags, Mastodon will not generate a preview. Page authors should include both og: and twitter: tags for maximum compatibility.

Conclusion

You can now diagnose and fix missing link previews in Mastodon by checking the source page for Open Graph tags, appending a query parameter to bypass the cache, or adjusting the server settings. If you are an instance administrator, remember to flush the PreviewCard table in the Rails console and verify that the LinkCrawlWorker sidekiq queue is active. For a long-term solution, encourage content creators to include og:title, og:description, and og:image tags in their pages. This ensures previews work on Mastodon and other platforms that follow the Open Graph standard.