URL Unfurl Troubleshooting Guide — Fix Link Preview Issues
Link preview broken? URL unfurl returning an empty card on Slack, the wrong image on LinkedIn, an outdated title on Facebook? This guide covers every common failure scenario, how to diagnose the root cause, and the specific fix for each — all organized by symptom so you can skip straight to the one you're seeing.
Start here: paste your URL into TryUnfurl.com. It shows exactly what platform crawlers read from your page, which narrows down the cause of any URL unfurl issue in seconds.
Understanding the URL Unfurl Process
Before troubleshooting, it helps to know exactly what's happening under the hood. Every URL unfurl follows the same pipeline:
- Platform crawler fetches your page (Slackbot, Discordbot, facebookexternalhit, LinkedInBot, Twitterbot, WhatsApp, and so on) using an HTTP GET — no JavaScript, no cookies, no login.
- The crawler parses the HTML
<head>and pulls Open Graph, Twitter Card, and standard HTML meta tags. - The platform resolves the preview image — it follows
og:image, downloads the file, and validates dimensions. - A preview card is rendered using the platform's specific priority order and layout rules.
- The card is cached — sometimes for hours, sometimes for days, occasionally indefinitely until you force a refresh.
When a link unfurl breaks, the failure is almost always in one of those five steps. Knowing which step is the one that turns a two-hour investigation into a two-minute fix.
Step 1 — Identify What's Actually Wrong
Before fixing anything, get precise about the symptom:
| What you see | Go to |
|---|---|
| No preview appears at all | No preview at all |
| Preview shows but wrong title | Wrong title or description |
| Preview shows but no image | No image in preview |
| Preview is outdated / showing old content | Outdated cached preview |
| Preview works on some platforms, not others | Platform-specific issues |
| Preview was correct, now suddenly broken | Preview broke unexpectedly |
No Preview at All
When nothing appears — just the raw URL with no card.
Diagnosis checklist:
- Paste the URL into TryUnfurl.com — if metadata appears there, the platform is blocking the preview for a different reason
- View your page source and search for
og:title— if it's not there, add Open Graph tags - Check if the page returns a non-200 HTTP status (redirect chain too long, 404, 500)
- Check if your bot protection is blocking the platform's crawler
Common causes and fixes:
| Cause | Fix |
|---|---|
| No Open Graph tags on the page | Add og:title, og:description, og:image, og:url |
| Crawler blocked by firewall or WAF | Allowlist Slackbot, Discordbot, facebookexternalhit, LinkedInBot, Twitterbot |
| Too many redirects (>5 hops) | Reduce redirect chain to 1–2 hops |
| Page returns 4xx or 5xx | Fix the URL or server error |
| JavaScript-only rendering | Use SSR or SSG to inject meta tags in initial HTML |
Wrong Title or Description
A preview appears but shows the wrong text.
Diagnosis checklist:
- Check TryUnfurl — does it show the correct or incorrect title?
- If correct on TryUnfurl: the platform is showing a cached version — force a refresh
- If incorrect on TryUnfurl: your metadata is actually wrong — fix the tags
- Look for conflicting tags — do
og:title,twitter:title, and<title>all agree? - Check whether the page has multiple conflicting
og:titletags
Common causes and fixes:
| Cause | Fix |
|---|---|
| OG tags contain old copy | Update og:title and og:description in the HTML |
| Platform cached old metadata | Use platform debugger tools to force a re-scrape |
| Conflicting OG and HTML title values | Make og:title and <title> consistent |
Multiple og:title tags on the page |
Remove duplicates — only one og:title should exist |
| JavaScript injecting tags (no SSR) | Move meta tags to server-rendered HTML |
No Image in Preview
A preview card appears but the image slot is empty.
Diagnosis checklist:
- In TryUnfurl, is
og:imagelisted? If not, add it - Open the
og:imageURL in a private/incognito window — does it load? - Is the image URL absolute HTTPS? (not relative, not HTTP)
- Is the image large enough for the platform? (minimum 1200 × 630 px for universal compatibility)
- Is
og:image:widthandog:image:heightdeclared?
Common causes and fixes:
| Cause | Fix |
|---|---|
og:image tag missing entirely |
Add og:image with an absolute HTTPS URL |
Relative URL (/images/og.jpg) |
Change to full URL: https://yourdomain.com/images/og.jpg |
| Image returns 404 | Fix the image URL or upload the image |
| Image too small (below platform minimums) | Use a 1200 × 630 px image |
| Image blocked by robots.txt | Remove image path from robots.txt Disallow rules |
| Image behind authentication | Move image to a publicly accessible URL |
| WebP format | Convert to JPG or PNG for maximum compatibility |
Outdated Cached Preview
You fixed your metadata but the preview still shows old content.
Diagnosis: Paste your URL into TryUnfurl.com — it fetches with no cache. If it shows the correct updated metadata, your page is fixed and the problem is purely the platform's cached result.
Fix by platform:
| Platform | How to clear |
|---|---|
| Sharing Debugger → Scrape Again | |
| Twitter / X | Card Validator — each validation clears the cache |
| Post Inspector → Regenerate | |
| Slack | Delete the message, re-share the link |
| Discord | Add ?v=2 to the URL when re-sharing |
| Delete and resend |
Also check: is your CDN caching the old HTML? If so, purging the platform cache won't help — purge your CDN cache first.
Platform-Specific Issues
Slack only
- Slackbot blocked by WAF? Add
Slackbotuser-agent exception - JavaScript rendering? Slackbot doesn't execute JS
- See the full Slack Link Preview troubleshooting guide
Discord only
- Add
?v=2to URL to bypass Discord's embed cache - Discord needs at least 300 × 157 px for images
- See the full Discord Preview troubleshooting guide
LinkedIn only
- LinkedIn requires a minimum 1200 × 627 px image for the large card format
- LinkedIn ignores Twitter Card tags — only reads Open Graph
- Use the Post Inspector to force a re-scrape
Twitter / X only
twitter:cardmust be explicitly set — without it, X may not show any card- For large image format: set
twitter:cardtosummary_large_image
Preview Broke Unexpectedly
The preview was working and now it's broken, with no obvious change.
Common causes:
og:imageURL changed or the image file was deleted- A CDN or image hosting provider changed the URL structure
- A new WAF or security rule is now blocking crawlers
- A recent deploy introduced a JavaScript rendering regression
- The platform's own crawler changed behaviour (rare, but happens)
Diagnosis: Paste the URL into TryUnfurl.com and look at the raw og:image value — then open that URL directly in a private browser window to confirm whether the image still loads.
Advanced Unfurl Optimization
Once the URL unfurl card renders correctly, a few extra moves separate a correct preview from one that actually earns the click:
- Set a site-wide default
og:imageso no page ever ships naked. - Design the
og:imagefor the crop. Keep the brand and the value prop in the center 800×400px; the edges get trimmed on mobile. - Keep
og:titleto 55–60 characters. Anything longer gets truncated on Facebook and LinkedIn. - Write
og:descriptionfor the click, not for SEO. 100–155 characters, benefit-led. - Serve the
og:imagefrom a CDN with long cache headers. Crawlers re-fetch often. - Use
og:typecorrectly —articlefor posts,productfor commerce,websitefor the rest. - Server-render critical tags. If you use a JavaScript framework, Open Graph tags must live in the initial HTML, not be injected client-side.
- Audit monthly. Run evergreen pages through the bulk URL unfurl checker — CMS and theme updates silently break link unfurling more often than you'd think.
If you have high-traffic pages, also consider the unfurl API — it lets you build URL unfurl validation into CI/CD so broken Open Graph unfurl cards never ship.
Frequently Asked Questions
Why is my URL unfurl returning a blank card?
The most common causes are: (1) missing og:image, (2) og:image returning 403/404 to the crawler, (3) all Open Graph tags being injected via JavaScript (crawlers don't run JS), or (4) a WAF blocking the platform's user-agent. Paste the URL into TryUnfurl to see exactly what a crawler sees.
How do I force a URL unfurl refresh on Facebook or LinkedIn?
Run the URL through the Facebook Sharing Debugger or LinkedIn Post Inspector and click the re-scrape button. That forces the platform to re-fetch with your updated tags. See how to refresh a link preview for every platform's workflow.
Why does the URL unfurl look different on Slack vs LinkedIn?
Each platform reads tags in its own priority order. LinkedIn ignores Twitter Card tags; Slack prefers Open Graph but falls back to HTML title/description; X/Twitter prefers twitter:* tags over og:*. Make both sets consistent and the cards will converge.
My URL unfurl works locally but not when I share the live URL — why?
Almost always a server-side rendering gap. Dev environments with client-side rendering look fine in your browser but return no meta tags to crawlers. Switch to SSR, SSG, or pre-render so Open Graph tags are in the initial HTML.
How do I prevent URL unfurl regressions after deploys?
Build a URL unfurl check into CI/CD. The TryUnfurl unfurl API lets you assert og:image, og:title, and og:description after every deploy, so a broken link unfurling change fails the pipeline before it reaches users.
Still Stuck?
If you've worked through this guide and still can't identify the problem, TryUnfurl.com shows the full raw metadata your page is serving — use that output as the starting point for any deeper investigation, or to confirm exactly what each platform's crawler is seeing.
→ Diagnose your link preview now · → Bulk-check 100 URLs at once