How to Fix Discord Link Previews for a Game Site
Someone in our clan Discord posted a link to a raid guide I had spent a weekend writing, and the embed came out as the site name, a grey placeholder square, and the first eleven words of the cookie notice.

Someone in our clan Discord posted a link to a raid guide I had spent a weekend writing, and the embed came out as the site name, a grey placeholder square, and the first eleven words of the cookie notice. Three people asked what the link was before anyone clicked it. The page itself was fine. The preview was the whole problem, and on a community site most of your traffic arrives through exactly that preview.
Discord builds those embeds from Open Graph tags, and it does it with a fetcher that behaves nothing like a browser. It runs no JavaScript, it gives up quickly, it proxies images through its own cache, and it ignores most of what an SEO plugin thinks it has configured. Once you know those four facts the fix takes about twenty minutes per site.
What the Discord fetcher actually reads
When a link lands in a channel, Discord requests the page with its own user agent and parses the raw HTML it gets back. Anything your theme injects after page load does not exist as far as the embed is concerned. If you render meta tags client side, through a React front end or a tag manager, the embed will stay empty no matter how correct the tags look in your browser inspector.
View source rather than inspect element. The tags have to be in the bytes the server sends.
| Tag | What Discord does with it | Practical limit |
|---|---|---|
| og:title | Bold heading line of the embed | Around 60 characters before it wraps badly on mobile |
| og:description | Body text under the title | Roughly 150 characters, truncated after that |
| og:image | The picture, proxied and cached by Discord | Absolute URL only, 1200 by 630 for the large layout |
| twitter:card | Set to summary_large_image to get the wide image | Without it you often get a small thumbnail |
| theme-color | Colour of the vertical stripe on the left edge | Hex value, one per page |
That last one is the cheapest win on the list. A guild site with a consistent stripe colour reads as deliberate in a channel full of grey embeds, and it costs one line in the head.
The image is where most gaming sites fail
Three failure modes, in the order I have run into them.
The URL is relative. Open Graph requires an absolute URL, and a path like /img/raid-guide.jpg gets dropped silently. Build it from the site URL, not from the post permalink.
The image is blocked. Fan sites that added hotlink protection to stop other wikis leeching their screenshots also block the Discord proxy, because the proxy sends no referer from your domain. If you have set that up, allow the proxy host explicitly or exempt your Open Graph image directory. The trade-offs are the same ones in stopping image hotlinking on a fan site.
The image is the wrong shape. Discord crops the large layout to about 1.91 to 1. A tall character portrait or a 1080 by 1080 tier list card gets its top and bottom removed, and the part you cared about is usually the part that goes. I keep a 1200 by 630 template in GIMP with the text in the middle third, and pasting a screenshot into it takes under a minute.
Keep the file under roughly 300 KB. Discord's fetcher is not patient, and I have watched a 2.4 MB PNG time out on a shared host often enough to stop testing my luck. Alt text does nothing for the embed, though you still want it on the page itself for the reasons in alt text for game screenshots.
The cache is not the one everyone tells you to clear
Standard advice: paste the URL into the Facebook sharing debugger, hit scrape again, done. That advice is wrong for Discord, and it wastes a lot of people's evenings. Discord keeps its own metadata and image cache, and nothing you do on another platform's debugger touches it.
What works, in order of how much I trust it. Change the image filename whenever you change the image, because a fresh URL has no cache entry at all and the new picture appears instantly. That is the only method I rely on before an event announcement goes out.
Next best, test in a private channel with a query string appended, something like ?p=2. Discord treats that as a different URL, so you see your current tags without waiting for anything to expire. Keep a scratch channel for exactly this.
After that you are down to waiting. Entries do expire on their own, and in my notes it has usually taken a few hours rather than days, though I have had one stubborn page hold a stale description overnight. Deleting and reposting the message refreshes nothing, whatever the forum threads say, so try it once and move on.
The practical rule: treat your Open Graph image as immutable. Version the filename, never overwrite it.
Per-page tags beat one sitewide image
Plenty of clan sites set a single site-wide Open Graph image, the guild logo, and call the job finished. Every link in the Discord then looks identical, which defeats the point. Members cannot tell the patch notes from the signup sheet without reading the title line carefully, and in a busy channel they will not.
If you run WordPress, the SEO plugin you already have exposes a social image field per post, separate from the featured image. Fill it for the pages that get shared: patch notes, event pages, the roster, the two or three guides that carry your traffic. Leave the rest on the sitewide default. On a 200 page wiki I did about fifteen and stopped, and that covered nearly everything anyone actually posted.
The description field deserves the same treatment. The same sentence that earns a click from search earns a click from a channel, so the thinking in writing meta descriptions that earn clicks transfers directly. Write it for a person skimming on a phone, not for a crawler.
FAQ
Why does my Discord preview show no image at all?
Usually a relative og:image URL, an image blocked by hotlink protection, or a file too large to fetch in time. Check the raw page source first to confirm the tag exists in the server response, then open the image URL in a private window to confirm it loads without a session.
How long does Discord cache a link preview?
Not documented, and variable. A few hours is typical in my experience, with occasional entries lasting much longer. Change the image filename or append a query string instead of waiting.
Do I need Twitter tags if I only care about Discord?
One of them helps. Setting twitter:card to summary_large_image is what triggers the wide image layout in many cases, so include it even if nobody on your site uses that platform.
Does the theme-color tag affect anything else?
Mobile browsers use it to tint the address bar, so pick a colour that suits both. One hex value in the head covers the embed stripe and the browser chrome together.
More in Web Tips
Web Tips
How to Lazy Load YouTube Embeds on Game Guide Pages
A boss guide with six embedded YouTube clips feels helpful to write.
Web Tips
How to Stop Image Hotlinking on a Gaming Fan Site
The first time hotlinking cost me money, it was a boss fight screenshot.
Web Tips
How to Edit robots.txt Without Blocking Your Own Site
Your traffic dropped by half over a weekend, and the only change anyone remembers is "a small tweak to the robots.txt file".