Troubleshooting guide

Teams link preview not showing?

Microsoft Teams builds a link preview from your page’s Open Graph tags, or its title and description, when someone pastes the link into a chat or channel. Here’s what to check when the preview is missing or out of date, based on Microsoft’s own documentation.

The check opens on the Teams preview and flags missing tags and images that can’t be loaded.

What Teams needs

Tags: og:title, og:description and og:image, or the page’s <title> and description
Image: 1200×630 recommended. Microsoft publishes no size limit
Access: A public page. Pages behind a login get no preview
Admin: The Allow URL previews messaging policy must be on

From Microsoft’s Share to Teams docs ↗

Common causes and fixes

1
The tags are missing or added by JavaScript

Teams reads og:title, og:description and og:image, falling back to the page’s title and description. It reads the HTML your server sends, so tags a JavaScript framework adds later are never seen.

Fix: Check your page to see which tags the server sends, then copy the generated code into your <head>.
2
The page needs a login

Microsoft’s docs are clear: a link that requires authentication can be shared, but no preview is created. Intranet pages, staging sites and pages behind a paywall show up as plain links.

Fix: Serve the tags to visitors who aren’t signed in, or accept a plain link for private pages.
3
Your organization turned previews off

Teams admins control link previews with the Allow URL previews setting in messaging policies. When it’s off, nobody covered by that policy sees previews, for any site.

Fix: Nothing to fix on your page. A Teams admin can turn Allow URL previews on in the Teams admin center, under Messaging policies.
4
Bot protection blocks Teams

Firewalls and bot protection can stop Microsoft’s preview service from reading the page. Developers report that it identifies itself with SkypeUriPreview in the user agent.

Fix: Let that user agent through your bot protection, and open the page and image in a private window to confirm they’re public.
5
The image doesn’t show

The image needs a full https:// address that loads without a login. Relative addresses, SVG files and very small images often leave the preview without a picture.

Fix: Use a 1200×630 JPG or PNG at a full https:// address. The OG image generator makes one in your browser.
6
Teams is showing an old version

Teams keeps the preview it fetched earlier, and caches images by their address. Microsoft doesn’t document a way to refresh it.

Fix: Paste the link with a query string such as ?v=2, and give a replaced image a new file name.

Still seeing the old preview?

Teams has no tool to refresh a preview, and messages already sent keep theirs. To test a fix, paste the link with a query string such as ?v=2, which Teams treats as a new link.

Send this instead

example.com/page?v=2

Next fix, next number: ?v=3

Questions

What people ask when the fixes above don’t explain it.

Why do previews work in one Teams organization but not another?

Link previews are an admin setting. Each organization, and each messaging policy inside it, can turn Allow URL previews off, so the same link can show a preview for one company and not for another.

Can I remove the preview from my message?

Yes. Before sending, close the preview above the message box. The link is sent without it.

Why do SharePoint and OneDrive links look different?

Links to Microsoft 365 files show as file cards that Teams builds from the file itself. Open Graph tags only shape previews of regular web pages.