How to debug link previews
Link previews can make or break a click. Learn how Open Graph and Twitter Card metadata works, and which tools help you debug previews both locally and after deployment.
Sebastian Guhl
Working Student
April 2, 2026
When sharing a link to a website, most platforms automatically generate a preview with a title, description, and image. These previews appear in apps like WhatsApp, Telegram, or LinkedIn and often determine whether someone clicks the link or scrolls past it.
But what happens when that preview looks wrong? While working on our website, we ran into exactly this problem. In this post, I’ll walk through how social share previews work and how to debug them when things don’t look the way they should.
How link previews work
The link preview is defined by a set of meta tags in the HTML <head> of a webpage. These tags can specify information such as a title, description, or preview image. When you share a link on a social media app, the platform fetches these tags and generates a preview that matches the visual style of the specific app.
Most platforms rely on the Open Graph Protocol to determine which metadata to use. The main exception is X (formerly Twitter), which supports its own Twitter Card tags. However, if those tags are not defined, it will usually fall back to the Open Graph metadata. If Open Graph tags are missing entirely, most social media platforms will use fallbacks as an attempt to guess how a preview for your website should look, which can go well if you're lucky, but the results can be unpredictable.
The following table provides an overview of some important Open Graph and Twitter tags that can be defined.
| Tag | Platform | Purpose / Description |
|---|---|---|
og:title | All major platforms | The title of the page shown in the preview. Usually bolded. |
og:description | All major platforms | A short summary of the page content displayed in the preview. |
og:image | All major platforms | URL of the preview image shown when the link is shared. |
og:url | All major platforms | Canonical URL of the page. This ensures the correct link is shared. |
og:type | All major platforms | Type of content, for example website or article. Helps platforms format the preview. |
og:site_name | All major platforms | The name of the website or brand. Often displayed below the title. |
twitter:card | X / Twitter | Determines the type of Twitter card: summary (small image) or summary_large_image (large image). |
twitter:title | X / Twitter | Title displayed in the Twitter preview card. |
twitter:description | X / Twitter | Description displayed in the Twitter preview card. |
twitter:image | X / Twitter | Image displayed in the Twitter preview card. |
Both Open Graph and Twitter Cards allow you to define multiple images of different sizes. However, the Open Graph recommended dimensions are 1200×630 px, and in my experience a single image at these dimensions is usually sufficient, as most platforms expect this ratio and will simply crop or scale images that deviate from it.
There are many tags you can set to define how a link preview should look, but the most important ones are og:title, og:description, and og:image . In most cases, setting just these tags is enough to get a solid preview across most platforms. Defining them explicitly ensures your link previews look exactly as intended, instead of relying on unpredictable defaults that might pick the wrong title, description, or image.
Tools for debugging previews
Once the metadata is defined, the next step is verifying that platforms interpret it correctly. Fortunately, there are some tools that allow you to inspect the Open Graph metadata of a page and preview how the link will appear when shared.
In development
How do you check how a link preview looks before deploying your website to a server? After all, you can’t just send a link to localhost on WhatsApp.
One solution that worked really well for us is a browser plugin for chrome and firefox called socialsharepreview. It essentially does the same thing a social media app does when you send someone a link: it reads the meta tags defined in the HTML <head> and generates a preview of how the link might appear on platforms like Facebook, X, or LinkedIn.
This is especially convenient in a development setup with hot reloading, because any changes to your link preview configuration are immediately reflected in the browser plugin. You don’t need to take any extra steps, like pasting a link into a tool, to see the effect of your changes.
After deployment
Sometimes, the bots that fetch your website to generate a link preview see your site differently than your browser does. This is because these bots typically only read the HTML returned by your server and do not execute client-side JavaScript, so they can miss metadata added dynamically through client-side rendering. As a result, the preview may differ when you share a link to your deployed website, compared to what the browser plugin shows using the locally rendered HTML.
In this situation, another challenge arises when debugging link previews: social media platforms cache previews quite aggressively. This means that if you share a link to test your changes, you may still see an outdated preview, and it can take a long time before the platform fetches the updated metadata again. To work around this, there are tools like the socialsharepreview debugger and opengraph.xyz. These allow you to paste a link to your website and fetch the metadata just like a social media platform would, showing you how the preview looks without caching.
Both tools also validate your metadata, for example by checking whether your image has the recommended aspect ratio or whether your title has an appropriate length, and provide suggestions for improvement. The OpenGraph tool even includes a technical inspector, where you can edit your title, description, and image in an editor, see how the result would look in realtime and directly copy the corresponding meta tags you need to set in your HTML <head>.
Some platforms also provide their own debugging tools (e.g. Facebook Sharing Debugger, LinkedIn Post Inspector), which allow you to inspect the defined link preview.
With the right metadata in place and a few debugging tools at hand, link previews become easy to control, and a few minutes spent setting up proper metadata can make a big difference in how your content is perceived when shared. If you’ve had your own struggles with link previews or found clever ways to handle them, feel free to reach out. We’d love to hear about it and are happy to help!
Key takeaways
- Always define
og:title,og:description, andog:imageto control your link previews - Test previews locally using a browser plugin
- Test deployed links with OG/Twitter debugging tools
- Remember that social media platforms cache previews, so changes might not appear immediately