Paste a link to your site into a chat and look at what comes back. On a lot of WordPress sites that card shows a logo in a grey box, a stretched thumbnail, somebody’s avatar, or nothing at all.
So you go into WordPress and start looking for the setting. Settings, Media. Nothing. The post editor. Nothing obvious. The Customizer. Nothing. You are looking for a control that does not exist, and that is not your fault.
The share card is the one piece of your design that gets seen by people who have not visited yet. It is a shop window you never look at, which is exactly why it stays broken for years.
This article is about finding where the picture actually comes from, and fixing it at that layer instead of guessing. Everything measured below was measured on this site, with the commands printed so you can run them against your own.
Core writes no Open Graph tags
This is the fact that reframes the whole problem. WordPress core does not emit og:image. It does not emit og:title, og:description, og:url or twitter:card either. No core function writes a single Open Graph tag into wp_head.
Search a WordPress install for the string and you find exactly one file in wp-includes that mentions og:image: wp-includes/rest-api/endpoints/class-wp-rest-url-details-controller.php, where it appears inside a regular expression alongside og:image:url. That is the endpoint behind the link preview in the block editor, and it is core reading somebody else’s Open Graph tags to build a preview card for a URL you pasted. Core knows how to parse Open Graph perfectly well. It has simply never been in the business of producing it.
Which means every Open Graph tag on your site was put there by something you installed. An SEO plugin, a social plugin, a line in your theme’s header.php, or a snippet somebody added in 2019 and forgot. When the card is wrong, the answer is never in WordPress settings, because WordPress is not the thing making the decision.
Step one is therefore not “where do I change this”, it is “who is emitting this”. Everything else follows from that answer.
What the scraper actually does
When you paste a link, the platform sends a bot to fetch that URL. Facebook’s identifies itself as facebookexternalhit, and the others behave similarly. Four things about that bot decide whether your card works.
- It requests the raw HTML. It does not run JavaScript. If your theme or a plugin injects Open Graph tags client side, the scraper sees an empty head.
- It reads the
<head>, and crawlers generally stop reading after the first chunk of the document. Tags printed late, or printed into the body, are unreliable. - It treats the first
og:imageas the card image. If two plugins both emit one, the loser is whichever hooks in later. - It then makes a second, separate request for the image URL. That request can fail on its own, and when it does you get a card with a title and no picture.
Then it caches. This is the part that wastes everybody’s afternoon. You fix the tag, you paste the link again, and the old card comes back, because the platform is serving what it scraped days ago. It is not that your fix did not work. It is that nothing re-fetched.
That cache is the entire reason the debuggers exist. The Facebook Sharing Debugger and the LinkedIn Post Inspector both do the same two useful things: they fetch your URL fresh, and they show you the tags they actually parsed rather than the tags you believe you wrote. The Facebook one additionally lets you scrape again and purge that URL from its cache, which is the button you want after any change. X has a card validator as well, though public access to it has come and gone over the years, which is one more reason to keep a curl command in your pocket.
The image is cached separately from the tags, which is why replacing a file at the same URL is the slowest possible way to change a card. Uploading under a new filename gets picked up far more reliably.
The fallback chain
A typical WordPress setup with an SEO plugin walks down a chain until it finds an image. It looks roughly like this:
- An explicit social image set on that individual post, in the plugin’s Social tab.
- The featured image.
- The first image found in the post content.
- A site-wide default image configured once in the plugin settings.
Every step down that chain is a place a wrong picture comes from, and the symptom tells you how far down you fell.
Step one is the field almost nobody knows exists. It sits in a Social tab inside the post editor sidebar, next to the SEO fields, and it is the only one of the four that lets you make a card on purpose. If you have never opened it, you have never used step one.
Step two is where most sites live, and it works, but only by accident. Featured images are sized for your theme’s layout, not for a share card. A 16:9 hero, a tall portrait or a square product shot all become the card, and all three get cropped by the platform to fit a shape nobody designed for.
Step three is where the genuinely strange cards come from. The first image in the content is often not the point of the article. It is a screenshot of a settings panel, an inline icon, a small diagram, a decorative divider, or an author avatar that happens to be an <img> early in the markup. It gets shared to a few thousand people as the face of your post.
Step four is the logo in a grey box. It is not a bug, it is the plugin doing exactly what you told it in a settings screen you visited once. It is fine as a floor. It is a bad ceiling.
What this site emits
Rank Math is the SEO plugin here, currently version 1.0.276, so I fetched three of my own URLs as a bot and read what came back. It is a fair example precisely because it is not perfect.
The front page is clean. It falls through to the site-wide default, which is a purpose-made JPEG at exactly 1200 by 630 pixels and 117,284 bytes on the wire. Rank Math stores that URL as open_graph_image in the rank-math-options-titles option, with open_graph_image_id pointing at the attachment and twitter_card_type set to summary_large_image. One default, set once, and every page that has nothing better lands on it. The tag comes out twice, as og:image and again as og:image:secure_url, which is normal and harmless.
A blog post is a step down. There is no explicit social image on it, so it falls to the featured image, which comes out as a 1600 by 900 PNG at 183,818 bytes. That is 1.78:1, and the large card wants 1.91:1, so the platform trims roughly thirty pixels off the top and thirty off the bottom. A small crop rather than a disaster, but it is a crop nobody chose, and a PNG is a heavier way to ship a photographic card than a well encoded JPEG would be. Correct in structure, sloppy in specification.
The third result is the one worth your attention. I requested a URL that does not exist on this site. The server correctly returned HTTP 404, and the page still emitted a confident-looking Open Graph block: og:type of article, the site default image at 1200 by 630, twitter:card set to summary_large_image, and an og:title reading “Page Not Found” followed by the site name. That title is Rank Math’s 404_title template, stored as Page Not Found %sep% %sitename%, rendered out. The only sign of trouble is what is missing: no og:url and no og:description.
So a mistyped link, a URL that changed slug, or a post that got deleted does not produce an obviously broken card. It produces a normal looking card with your branding on it that says Page Not Found in small grey type. If you have ever wondered why a share “looked fine” and still got no clicks, check that the URL resolves before you touch anything else.
The numbers
There is very little to memorise here, and getting these four right removes most of the failure modes.
1200 by 630. This is the workhorse and it is what the large card format expects. It sits at 1.91:1. LinkedIn documents 1200 by 627, which is the same card with three pixels of rounding, so one file serves both. Anything wider than 1.91:1 gets pillarboxed, anything squarer gets its top and bottom taken.
200 by 200 is the floor. Below that, platforms do not render a small version of your image, they ignore it and fall back to a plain text card. This is how a favicon or a 150 by 150 thumbnail ends up producing no image at all rather than a tiny one.
The URL must be absolute. A relative path in og:image is not resolved and not reported. It is silently dropped, the tag is present in your source, and the card behaves as though you never set one. Include the scheme and the host, every time. Mixed protocols count too: an http:// image URL on an https:// page is a common cause of a card that works in one place and not another.
Keep the file modest. Platforms cap what they will fetch, in the low single-digit megabytes, and that cap is the reason a beautiful 4 MB PNG card silently becomes no card. There is no need to be precious about it. The default on this site is 117 KB and it looks fine at every size a feed will ever show it.
That last point is the one place a tool earns a mention here: WunderPaint’s image processor resizes and re-encodes a batch of images in one pass, in your own browser, with the originals kept.
The registered size trap
This is the WordPress-specific failure worth the whole article, because the tag looks completely correct and the card still does not work.
Sensible theme code does not hand the platform a 4000 pixel original. It asks for a registered size built for the job:
add_image_size( 'og-image', 1200, 630, true );
// ...later...
$url = get_the_post_thumbnail_url( $post_id, 'og-image' );That is the right instinct, and it has two ways of going quietly wrong.
The first is registering the size after the images were uploaded. WordPress generates derivative files at upload time and records them in the sizes array inside _wp_attachment_metadata. A size added later has no entry for older attachments, so image_get_intermediate_size() returns false, and image_downsize() in wp-includes/media.php hands back the full-size URL instead. The tag is present, the URL resolves, and what you just gave the scraper is the untouched original: possibly 4000 pixels wide, several megabytes, and the wrong shape. The platform hits its fetch cap and shows nothing.
The second is worse and harder to spot. image_get_intermediate_size() reads the metadata array and never touches the filesystem. It does not check that the file it is describing still exists. If your uploads were migrated, or restored from a partial backup, or run through a plugin that deletes “unused” image sizes to save disk, the metadata still lists the size and the file is gone. WordPress confidently builds a URL for it. The tag is present, the URL 404s, and the platform renders a card with a title and an empty grey rectangle.
Both cases have the same fix, which is regeneration: rebuilding the derivative files so that what the metadata claims and what is on disk agree. If any of this is unfamiliar, how one upload becomes many files is the piece to read first, because this whole trap is just that mechanism seen from the outside.
The practical lesson is blunt: never trust that an og:image URL works because it is in the source. Fetch it.
Verifying from the command line
Before you touch any settings, find out what is actually being served. Two commands answer almost every question in this article, and they are the two I used to write the section above.
First, see the page as the scraper sees it. Set the user agent, because caching layers, firewalls and some CDNs serve bots differently from browsers, and it is the bot’s copy you care about:
curl -s -A "facebookexternalhit/1.1" https://example.com/your-post/
| grep -Eo '<meta[^>]*(og:|twitter:)[^>]*>'Read that output for three things: is there an og:image at all, is it the picture you expected, and is there more than one. Two og:image tags means two plugins are both writing them, and the fix is to turn one off rather than tune both.
Second, take the URL out of that tag and fetch it on its own. This is the request the platform makes separately, and the one that fails silently:
curl -sI https://example.com/wp-content/uploads/2026/07/card.jpg
| grep -iE '^(HTTP/|content-type|content-length)'You want 200 OK, an image content type, and a content length that is a plausible number of kilobytes. A 404 is the registered size trap. A content type of text/html means you are being handed an error page or a login redirect. A content length in the millions means the platform will refuse it.
Run both against your homepage, against a post with a featured image, and against a post without one. Those three cover nearly every way this breaks.
Emitting the tags yourself
If you have no SEO plugin, nothing on your site is writing these tags and no amount of configuration will change that. This is the minimum that does the job. It belongs in a place custom code survives an update, which in practice means a small site-specific plugin or a child theme, never the parent theme’s functions.php.
add_action( 'after_setup_theme', function () {
add_image_size( 'og-image', 1200, 630, true );
} );
add_action( 'wp_head', 'mysite_open_graph_tags', 5 );
function mysite_open_graph_tags() {
// Do nothing if an SEO plugin is already emitting Open Graph tags.
if ( defined( 'RANK_MATH_VERSION' )
|| defined( 'WPSEO_VERSION' )
|| defined( 'AIOSEO_VERSION' ) ) {
return;
}
if ( ! is_singular() ) {
return;
}
$post_id = get_queried_object_id();
$src = false;
$thumb = get_post_thumbnail_id( $post_id );
if ( $thumb ) {
// Returns array( url, width, height, is_intermediate ) or false.
$src = wp_get_attachment_image_src( $thumb, 'og-image' );
}
$image = $src ? $src[0] : get_stylesheet_directory_uri() . 'https://cdn.wp-image-editor.com/img/default-og.jpg';
$width = $src ? $src[1] : 1200;
$height = $src ? $src[2] : 630;
$tags = array(
'og:type' => 'article',
'og:site_name' => get_bloginfo( 'name' ),
'og:title' => get_the_title( $post_id ),
'og:description' => wp_strip_all_tags( get_the_excerpt( $post_id ) ),
);
foreach ( $tags as $property => $content ) {
printf(
'<meta property="%s" content="%s" />' . "n",
esc_attr( $property ),
esc_attr( $content )
);
}
printf( '<meta property="og:url" content="%s" />' . "n", esc_url( get_permalink( $post_id ) ) );
printf( '<meta property="og:image" content="%s" />' . "n", esc_url( $image ) );
printf( '<meta property="og:image:width" content="%d" />' . "n", (int) $width );
printf( '<meta property="og:image:height" content="%d" />' . "n", (int) $height );
printf( '<meta name="twitter:card" content="summary_large_image" />' . "n" );
}Four things in there are deliberate. The guard at the top is the important one: two sets of Open Graph tags is a worse problem than none, and checking for a constant the plugin defines is a more reliable test than checking whether a file is present. On this site RANK_MATH_VERSION is defined and reports 1.0.276, so this function would correctly do nothing.
Everything is escaped, because post titles contain quotes and ampersands and a stray apostrophe will truncate a tag. The fallback default uses get_stylesheet_directory_uri(), which returns an absolute URL including the host, since a relative one would be dropped.
The width and height are read back from wp_get_attachment_image_src() rather than hardcoded, and that matters for the reason described above: that function returns the URL, the width, the height and a flag saying whether it really is an intermediate size, so if the og-image file was never generated you get the full-size original and its real dimensions, and the tags stay truthful instead of describing a file that is a different shape. Note too that add_image_size() only affects uploads made after it is added, so an existing library needs regenerating first.
Whether what you emit is correct is worth checking rather than assuming, particularly if a plugin and a theme are both having a go at it.
Paste the head of one of your pages below. It lists every Open Graph and Twitter tag, flags the ones that appear twice because two plugins wrote them, and checks the parts that quietly break the preview: a relative image URL, a missing width and height, an image under the minimum, a WebP that half the networks will not render. Drop the image in as well and it shows the card in the three crops the networks really use.
Open Graph tag builder
A shared link shows a picture, a title and a line of text that nobody ever sees on the page itself. Paste the head of your page to read what the networks will find there, or fill the fields to write the block from scratch. The head is parsed in an inert document, so nothing in it is fetched or run, and an image you drop is measured in this tab and never uploaded.
or press Enter to pick one. It is measured in this tab, never sent anywhere.
The head is read with document.implementation.createHTMLDocument, a document with no browsing context. Scripts in it do not run, images in it are not fetched, and nothing is copied into this page as markup.
| Title | not read yet |
|---|---|
| Meta description | not read yet |
| Canonical | not read yet |
| html lang | not read yet |
The dashed box is the part of the picture that every one of the three crops keeps. Words and faces outside it are cut on at least one network.
Nothing checked yet.
| Weight | Tag | What it means |
|---|
X reads the og: tags when the twitter: ones are missing, so twitter:card is the only extra line most pages need. article:published_time and article:modified_time are written only when og:type is article.
WordPress writes no Open Graph tags of its own, so without a plugin or a theme snippet there are none at all. Rank Math writes them from the Social tab of its box under the editor, per post, with the site wide defaults under Titles and Meta. Yoast writes them from its own Social tab in the same place. Both take the featured image when no separate share image is set, which is why so many cards are cropped from a picture chosen for the top of the article.
In code the values are filters, not markup: Yoast has wpseo_opengraph_title, wpseo_opengraph_desc and wpseo_opengraph_image, Rank Math has rank_math/opengraph/facebook/og_title and the matching og_description and og_image. Filter the value, never print a second meta tag from your own hook: two plugins writing the same tag is the single most common fault on this list, and which copy a network picks is not up to you.
Facebook and LinkedIn keep the version they saw first, so a corrected tag changes nothing until their cache is cleared. Paste the address of the page into the Sharing Debugger at https://developers.facebook.com/tools/debug/ and into the Post Inspector at https://www.linkedin.com/post-inspector/ and press the button that reads it again. Those two lines are text on purpose: this page loads nothing from anywhere.
Overriding what a plugin emits
Most readers have a plugin, which means the snippet above is not the answer. The answer is a filter, and both major plugins provide one. Rank Math documents its filter as rank_math/opengraph/{$network}/image, where the network is facebook or twitter, so the concrete hook name is rank_math/opengraph/facebook/image. Yoast’s equivalent is wpseo_opengraph_image. Both pass the image URL, so one callback serves both:
function mysite_force_share_image( $image ) {
if ( ! is_singular() ) {
return $image;
}
$custom = get_post_meta( get_queried_object_id(), 'share_image_url', true );
return $custom ? esc_url( $custom ) : $image;
}
add_filter( 'rank_math/opengraph/facebook/image', 'mysite_force_share_image' );
add_filter( 'wpseo_opengraph_image', 'mysite_force_share_image' );Returning $image unchanged when your condition does not match is not optional politeness, it is what keeps the plugin’s own fallback chain intact for every page you did not mean to touch. Reach for this when you have a rule the plugin cannot express, such as a different card for one post type. For a single post, the Social tab in the editor is the right tool and no code is needed.
What belongs on the card
Once the plumbing is right, the picture itself is a design problem with an unusually tight brief. A share card is read in about a third of a second, at thumbnail size, usually on a phone, in a feed full of other things competing for the same glance.
The headline, big. Not your logo. The title is the reason somebody stops. Set it large enough to read at 300 pixels wide, which is considerably larger than feels right on your monitor.
One visual. A photograph, an illustration or a flat colour field. Not three things fighting for the same corner.
A small mark of who you are. A logo in a corner at a modest size, or just your site name. It builds recognition across dozens of cards without stealing the space the headline needs.
Contrast that holds. If text sits over a photograph, put a gradient or a scrim underneath it. Always, not only when the photograph happens to be busy, because the next photograph will not be.
Keep everything essential inside the middle two thirds. Several platforms crop toward a square for the small preview, and a headline that runs edge to edge in your design gets its first and last words taken. What does not belong on the card at all: your navigation, a paragraph of body text, a call to action, or the URL. There is a real, clickable link sitting right next to it.
Symptom and cause
No image at all, just a title and a link. Either there is no og:image tag in the head, or the image URL does not return a 200. Run both curl commands. If the tag is present and the file 404s, you are in the registered size trap.
The old image keeps coming back after you fixed it. Platform cache. Push the URL through the Facebook Sharing Debugger and scrape again, or through the LinkedIn Post Inspector. Replacing a file at the same URL is the slowest possible fix, so upload under a new filename instead.
Every post shows the same generic logo. You are landing on step four of the fallback chain. Nothing has an explicit social image, and either the featured images are missing or the plugin is not configured to use them.
A random screenshot or an icon from inside the article. Step three. The featured image is missing, so the first <img> in the content won by position.
The image is badly cropped. Aspect ratio, not resolution. The source is not 1.91:1 and the platform trimmed it to fit. Regenerate at 1200 by 630 rather than arguing with the crop.
A small square thumbnail instead of a wide banner. That is twitter:card set to summary rather than summary_large_image, or an image below the 200 by 200 floor causing a downgrade.
The card says Page Not Found. The URL 404s, and your SEO plugin’s 404 title template is being used as og:title. Check the link before you check anything else.
It works on one platform and not another. Usually a mixed protocol image URL, an image just over one platform’s file size cap, or one scraper’s cache being staler than another’s.
Where to start
The reason this problem feels intractable is that it looks like a WordPress setting and is not one. Core has never written an Open Graph tag and shows no sign of starting, so the question is always which of your installed things is speaking on your behalf, and whether the file it points at exists. Two curl commands answer both, faster than any amount of clicking through settings screens.
Once you can see what is being emitted, the fixes are small and permanent. Set a site-wide default at 1200 by 630 so the floor is somewhere you would not mind landing, check that featured images are actually reaching the tag, use the per-post social image on the handful of posts you genuinely care about, then regenerate so the sizes your code asks for exist on disk. My own site is one step short of that, and now I know exactly which step.
What makes it worth the hour is that the audience for a share card is people who have not visited your site yet. Every other piece of your design gets refined by the people already there. This one gets seen only by strangers, judged in a third of a second, and never reported back to you. A link that arrives as a designed card reads as something worth opening. A link that arrives as a grey rectangle reads as spam. Same article, same words, same site.
