Discord previews behave differently from Facebook or X because Discord's unfurl system caches harder and reverts slower — and most fixes that work elsewhere do nothing here. Paste a link into a server and Discord holds the scrape result for up to 30 minutes per URL. Post that embed into a message and it's locked there permanently, even after you fix your tags. Here's what Discord actually reads, why your card gets stuck, and the exact sequence that unsticks it.
What Discord Reads (and What It Ignores)
Discord's crawler, user-agent Discordbot/2.0, fetches your URL, parses the raw HTML, and builds the embed from og:title, og:description, og:image, og:url, and og:type. It executes no JavaScript. A React or Vue app that injects meta tags client-side shows Discordbot an empty shell page — bare link, no card. Server-render the tags (Next.js static generation handles this) or the embed never appears.
Discord's developer docs put hard limits on those same fields: og:title caps at 256 characters, og:description at 4096. Link cards display less — the client visually truncates the description, with most cards showing roughly the first 300 characters — so front-load the sentence that matters. The docs also note a quirk: embeds deduplicate by URL. Two embeds pointing at the same URL in one message collapse to whatever rendered first.
Why Your Card Is Stuck: Discord's Cache Model
This is the part most guides get wrong. Discord staff confirmed the caching rules in the official discord-api-docs issue tracker, and they explain nearly every "I fixed my tags but the preview didn't change" report:
- URL-level cache, up to 30 minutes. The first share of a URL triggers a scrape; Discord caches the result for that exact URL. Everyone posting the same link inside the window gets the cached card — no re-request, no matter how fresh your tags are.
- Message-level cache, permanent. An embed attached to a message never re-fetches. Editing the message doesn't fix it; deleting and re-pasting the same URL only hits the URL cache anyway.
- Image cache, separate. Discord proxies preview images through its own CDN (the embed structure literally carries a
proxy_urlfield). Image and metadata caches expire on their own schedules — people see a new title with an old image all the time.
The fix falls straight out of that model: make Discord see a different URL. Discord staff recommend appending a query string (?v=2) or even a bare fragment (#), which counts as a new URL without changing your page. That bypasses the 30-minute URL cache instantly. The permanent message cache has no cure: old messages keep the old card forever, but every fresh share of the new URL renders correctly.
OG Image Requirements That Matter
1200 × 630 at a 1.91:1 ratio is still the size Discord expects. Anything smaller risks being ignored; anything huge risks being dropped — the commonly reported ceiling sits around 8 MB, but the file that loads fast beats the file that's technically allowed. Keep the image under 300 KB and point og:image at an absolute HTTPS URL — relative paths and login-walled images render as nothing.
Two Discord behaviors surprise people. First, because every preview image is proxied through Discord's CDN, hotlink protection, referrer checks, or per-IP rate limits on your image host all break the card — even when the image downloads fine in a normal browser. Second, Discord treats animated previews as a separate medium: its embed types include gifv, officially defined as "animated gif image embed rendered as a video embed." An animated og:image is a gamble — video-style behavior, or a heavy file that stalls the scrape. Ship a static PNG or JPEG.
There Is an Official Debugger Now
The old advice — "Discord has no validator, paste it into a private server and hope" — is outdated. Discord runs an official embed debugger at discord.com/developers/embeds. Paste your URL and it shows exactly what Discordbot reads from your page. Per Discord's issue tracker, the debugger doesn't cache its results — every check is a fresh fetch, which makes it the fastest way to confirm a tag fix landed. One limit: it doesn't clear the cache for links already shared in a server. That stays the job of the query-string trick.
Troubleshooting Table: Symptom → Cause → Fix
| Symptom | Cause | Fix |
|---|---|---|
| No card at all | Discordbot blocked by robots.txt or WAF; missing or relative og:image; URL wrapped in < >, which suppresses embeds on purpose; SPA renders tags client-side | Allow Discordbot/2.0, ship an absolute HTTPS og:image, paste the bare URL, server-render the tags |
| Old title after a tag edit | Up to 30-minute URL cache | Append ?v=2 and re-share |
| New title, old image | Image and metadata caches expire separately | Bump the query string on the og:image URL itself |
| Old messages never update | Permanent message-level cache | Accept it; share the new URL going forward |
| Card renders on X, not in Discord | X falls back to twitter:card tags; Discord reads og: tags only | Add proper og:title / og:description / og:image |
| Description cut mid-sentence | Client-side truncation around the 300-character mark | Rewrite so the first 300 characters stand alone |
What About Video Links?
Video embeds are supported — video is a first-class embed type in Discord's API, and site owners do push og:video so visitors watch media inside the app, a use case documented in Discord's own issue tracker. The catch: the video URL must be a direct media file, not a page URL. And YouTube links bypass your OG tags entirely — Discord renders those through its own YouTube integration, so nothing on your side changes that card.
Test Before You Broadcast
Build the check into your publishing flow: run the URL through the official debugger first, then paste it into a scratch server before any big announcement. If the card renders there, it renders everywhere — for the next 30 minutes, anyway. And if you manage several links at once, our free OG checker surfaces the exact tags Discord will read — missing og:image, wrong size, bad URL — before your link lands in a server with ten thousand members. Rebuilding images from scratch? Pair it with our measured og:image size guide.