Discord Embed Not Showing: Fixing Link Embeds

What each part of a Discord embed comes from

Every visible piece of a Discord embed is filled from a particular tag or file. Once you know which one feeds which part, you can look at a broken card and go straight to the tag responsible, rather than guessing.

The layout switch trips up a lot of people. With twitter:card set to summary_large_image, the picture sits full width below the snippet. Without it, or with summary, Discord tends to shrink the picture into a thumbnail tucked beside the text, which is fine for a logo but wastes a designed share graphic.

How Discordbot fetches your page

As soon as a message with a link is sent, Discord's back end requests the address from its own servers. The request carries a user agent that includes Discordbot; at the time of writing it reads along the lines of Mozilla/5.0 (compatible; Discordbot/2.0; +https://discordapp.com). That single request decides what the card shows, and a few consequences follow.

• No JavaScript runs. Discordbot parses the HTML that arrives over the wire. Tags injected by a client-side framework, a tag manager or a consent script never reach it.
• No cookies, no session. Whatever an anonymous first-time visitor gets is what Discord gets. A cookie banner that replaces the page, a members-only redirect or a geo block all land on the card.
• The picture travels separately. Discord pulls the image down and re-serves it to members from its own media proxy, so the image URL has to be reachable on its own and send an image content type.
• Speed matters. If the origin takes several seconds to answer, Discord abandons the fetch and posts the bare link.

Proving the request arrived

Paste the link into your test channel, then look at the access log within a minute. This one-liner prints the status code and path of each recent Discordbot hit on a typical nginx or Apache combined log:

grep -i "discordbot" /var/log/nginx/access.log | tail -n 10 | awk '{print $9, $7}'

Read the result like this: nothing at all means something upstream (a CDN, a WAF or a hosting firewall) stopped the bot before your server saw it; 403, 429 or 503 means your stack refused it; 301 or 302 shows a redirect hop worth removing; 200 on the page but no line for the image means the image URL is the weak point.

Letting it through a firewall

On Cloudflare, a custom rule with the action Skip and an expression such as (http.user_agent contains "Discordbot") lets the crawler bypass managed challenges and Bot Fight Mode settings that support skipping; check your plan's options, because not every bot feature can be skipped on every tier. In Wordfence, ModSecurity or a host's "bad bot" list, whitelist the same user-agent string. Keep the rule narrow: allow the user agent on public pages and your share-image folder, not on admin paths.

A head section Discord reads cleanly

Here is a complete, working head for a fictional community event page. It gives Discord everything it uses: a headline, snippet, provider line, large picture, strip colour and an oEmbed file for an author line.

<head>
  <meta charset="UTF-8">
  <title>Winter LAN weekend, 14-15 February | Northgate Gaming Society</title>
  <meta name="description" content="Two days of casual and ranked play, a beginners' bracket on Saturday morning and hot food all weekend.">
  <link rel="canonical" href="https://example.co.uk/events/winter-lan">
  <meta name="theme-color" content="#2e8b57">
  <meta property="og:type" content="website">
  <meta property="og:site_name" content="Northgate Gaming Society">
  <meta property="og:url" content="https://example.co.uk/events/winter-lan">
  <meta property="og:title" content="Winter LAN weekend: 40 seats, book by 7 February">
  <meta property="og:description" content="Bring your own rig or borrow one of ours. Beginners' bracket Saturday 10am.">
  <meta property="og:image" content="https://example.co.uk/share/winter-lan-v1.jpg">
  <meta property="og:image:width" content="1200">
  <meta property="og:image:height" content="630">
  <meta name="twitter:card" content="summary_large_image">
  <link rel="alternate" type="application/json+oembed"
        href="https://example.co.uk/oembed/winter-lan.json"
        title="Winter LAN weekend">
</head>

A few details matter more on Discord than elsewhere. theme-color is a name= meta tag and wants a six-digit hex value; named colours and rgb() values are less dependable. Open Graph uses property=, Twitter card tags use name=, and mixing them up is a common reason a tag is ignored. Put all of this high in the head, ahead of big inline scripts, so a crawler reading the top of the document finds it quickly.

oEmbed: author and provider lines

oEmbed is a small JSON file, linked from the page head, that describes the page for services that embed it. Discord reads a linked oEmbed file and can use a few of its fields to add lines that Open Graph alone does not provide, most usefully an author line above the headline. It is optional, and plenty of good embeds never use it, but it is the tidy way to credit an organiser, a writer or a channel.

{
  "version": "1.0",
  "type": "link",
  "title": "Winter LAN weekend",
  "author_name": "Northgate Gaming Society events team",
  "author_url": "https://example.co.uk/events",
  "provider_name": "Northgate Gaming Society",
  "provider_url": "https://example.co.uk/"
}

Serve the file with Content-Type: application/json, over https, with no login in front of it. If Discord cannot fetch or parse it, it simply falls back to the Open Graph tags, so a broken oEmbed file rarely kills the whole card, but it can leave you wondering why the author line never appears.

• Static sites: write one JSON file per shareable page, or a single endpoint that takes the page address as a parameter.
• WordPress: core already publishes an oEmbed discovery link for posts and pages. Its author_name is the post author's display name, so check that name is one you are happy to show in every Discord server your posts reach.
• Video pages: if you want a playable embed, a correct og:video set (a direct https file or player address, with type, width and height) is the usual route; test it, because Discord decides for itself which sources it will play inline.

Server, channel and user settings that hide embeds

A perfectly tagged page can still post without a card, because Discord lets servers, moderators and individual members decide whether embeds appear. Before you touch your site, rule these out.

Permissions stack in Discord: a role can allow Embed Links while a channel override denies it, and the channel override wins for that channel. If you administer the server, the quickest check is to view the channel as the affected role using the permission preview, then paste a link that is known to embed, such as a large news site's article. If that link also shows no card, the problem is Discord-side, not your page.

Discord embed caching and how to get a fresh card

Discord keeps the embed it builds for an address and reuses it when the same address is posted again. Discord does not publish how long that lasts, and in practice it can be long enough to be annoying. There is no "fetch again" button of the kind Facebook's Sharing Debugger offers, so you work around the cache rather than clearing it.

1. Clear your own caches first. Purge the page and the share image in your CDN and any page-cache plugin. If Discord re-fetches and your CDN still hands it the old HTML, nothing changes.
2. Change the address slightly. Discord keys its cache on the exact URL, so https://example.co.uk/events/winter-lan?e=2 is treated as a brand-new link and fetched fresh.
3. Rename a changed image. Discord's media proxy may keep the old picture for the old image URL. Ship the new graphic as winter-lan-v2.jpg and update og:image, rather than overwriting winter-lan-v1.jpg.
4. Repost, do not edit. Messages already sent keep the card they were created with. Editing the message text is not a dependable way to rebuild it; a new message is.

Keep the canonical tag on the page pointing at the clean address, so the query-string version used for Discord is not seen by search engines as a separate page.

Bots and webhooks: custom embeds and switching them off

Links posted by a bot or a webhook are embedded from your page's tags in the same way as a member's link. A bot can also skip the page tags altogether and send its own embed object, which is how announcement bots, shop notifications and game-server status messages get a fully controlled card. In that object the strip colour is a decimal number rather than a hex string: #2e8b57 becomes 3050327.

curl -X POST "https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Booking is open for the winter LAN.",
    "embeds": [{
      "title": "Winter LAN weekend: 40 seats",
      "url": "https://example.co.uk/events/winter-lan",
      "description": "Beginners bracket Saturday 10am. Book by 7 February.",
      "color": 3050327,
      "image": { "url": "https://example.co.uk/share/winter-lan-v1.jpg" }
    }]
  }'

To post a link with no card at all, a bot can set the message's suppress-embeds flag (flag value 4) when it sends the message, or a member can wrap the address in angle brackets. That is handy for changelog posts that list many links, where a stack of cards would bury the text.

The fix, step by step

Platform notes and keeping embeds healthy

WordPress

Yoast SEO, Rank Math and similar plugins output Open Graph and Twitter card tags, but they do not all add theme-color. Add it once in your theme's header or with a small snippet hooked to wp_head. Check that only one plugin is writing og: tags; a theme and a plugin both doing it is the classic cause of Discord picking the wrong picture. Security plugins with "block fake bots" options deserve a look whenever the log shows 403s for Discordbot.

Shopify

Most themes print Open Graph tags from theme.liquid through a social meta snippet, using the product's featured image. theme-color is often missing; add it to the head in theme.liquid. Product cards on Discord use the first product image, so make sure it is a landscape-friendly shot rather than a tall cut-out that gets cropped awkwardly.

Static sites and frameworks

Hugo, Eleventy and Jekyll templates can emit every tag at build time, which Discordbot sees perfectly. With React, Vue or Svelte, use the framework's server rendering or static generation (for example Next.js metadata, Nuxt's head handling or SvelteKit's server-rendered head) so the tags are in the first response, not added after hydration.

Habits that prevent repeat problems

• Test every important link in your private channel before it goes into a busy server, because an announcement's card cannot be refreshed once hundreds of members have seen it.
• Version share images in the file name from the start (-v1, -v2) so a redesign never fights Discord's media proxy.
• Keep the Discordbot allow rule documented alongside your firewall settings, so a future security tidy-up does not quietly remove it.
• Set a site-wide fallback share image and theme-color in your template, so pages without their own graphic still post a finished-looking card.