Facebook Sharing Debugger: how to refresh a link preview
·7 min read
The Facebook debugger, officially the Sharing Debugger at developers.facebook.com/tools/debug, shows what Facebook's crawler reads from a URL and refreshes the link preview Facebook has stored for it. Log in to Facebook, paste the URL, click Debug, then click Scrape Again once your new title or image is live. Facebook caches every scrape and refreshes it on its own only about every 30 days, which is why a page you changed keeps sharing the old preview until you force a new scrape.
If Scrape Again still shows the wrong card, the problem is in your tags or your server, and the debugger's warnings tell you which.
What the Facebook debugger shows
The Sharing Debugger shows a URL the way Facebook's link crawler sees it. Meta's webmaster docs say it lists the meta tags the crawler scraped plus any errors and warnings, and that running a URL through it triggers a fresh scrape.
The result page lists warnings first, then the details of the last scrape, including the response code your server returned, the URL Facebook fetched in the end, any redirect path and a preview of the share card. Further down is every Open Graph property Facebook found.
You need a Facebook account. Logged out, the tool shows only a login prompt.
How to use Facebook's sharing debugger to refresh a preview
Refreshing a preview takes five steps, and the order matters because Facebook stores whatever it sees.
- Publish your change and purge your page and CDN caches. Otherwise Facebook scrapes the old HTML again.
- Open developers.facebook.com/tools/debug and log in.
- Paste the exact URL you plan to share and click Debug.
- Check when the URL was last scraped. If that time is before your change, click Scrape Again.
- Read the new preview and the warnings. If the title changed but the picture did not, read the next section.
To refresh many URLs, Meta's guide to changing link data documents a Graph API call that forces the same rescrape, POST /?id={url}&scrape=true, with the URL encoded.
Why your Facebook link preview is not updating
A Facebook link preview stops updating because Facebook caches the scrape, and Meta says its crawler refreshes link data automatically only every 30 days. Four more rules from Meta's docs explain most "I changed it and nothing happened" cases.
- Images are cached by URL. Replace the file at the same address and Facebook keeps the old picture. Upload the new image under a new file name, point og:image at it and scrape again. Leave the old file online, because published posts still load it.
- Old posts keep the old card. A rescrape changes future shares. For a post that is already up, open its menu and choose "Refresh share attachment".
- Titles freeze. Once a link has more than 50 interactions such as likes, comments and shares, its title can no longer change.
- The first share can lack a picture. Facebook fetches images asynchronously, so the first share of a new URL may have no image. Scrape the URL in the debugger before you post it, or set og:image:width and og:image:height.
LinkedIn has its own cache and refresh tool, covered in our LinkedIn Post Inspector guide.
What the debugger warnings mean
Each warning points at one tag or one server response.
Inferred property and missing og tags
An inferred property warning means a tag is missing and Facebook filled the value in from other tags on the page, such as the <title> element for og:title. The guess is often fine for the title and poor for the image. Add the tag explicitly and scrape again.
If the tag is in your page and the debugger still reports it missing, check the raw HTML your server sends, not your browser's inspector. Meta's crawler docs say Open Graph properties past the first 1 MB of the response are cut off, and a head stuffed with inline scripts can push them there.
og:image too small, too large or not downloaded
Image warnings mean Facebook could not use the og:image as given. Meta's limits are 200 by 200 pixels at least and 8 MB at most. A message that the image could not be downloaded or processed means the crawler got an error, a timeout or a response that was not an image.
Open the image URL in a private window. If it asks for a login, redirects or loads slowly, fix that first. Meta's link sharing FAQ says a share shows a white box when the image is unavailable, too big or slow to fetch.
Redirects and the fetched URL
When the URL you pasted redirects, the debugger shows the redirect path and the URL it finally fetched, and the card comes from that final page. A redirect to a login screen, cookie wall or country picker means Facebook previews that page instead of yours. Trace the hops with our redirect chain checker and make every variant of the address end at one page that returns 200.
Bad response codes
The response code is the HTTP status your server gave Facebook's crawler, and anything but 200 means no proper preview. A 403 or 503 often comes from a firewall or bot protection rule. A 404 means nothing is published at that address. A code of 0 means the crawler got no answer, and Meta's FAQ says it returns 0 when it cannot find an AAAA record, so check your DNS after moving servers.
The meta tags Facebook reads for a link preview
Facebook builds the card from Open Graph meta tags in the HTML <head>. Meta lists og:url, og:title, og:description and og:image as the basics for every page. og:type defaults to website and og:locale to en_US. Meta also lists fb:app_id, which you need only for Facebook Insights.
<head>
<title>Pro plan now $19 a month | Acme</title>
<link rel="canonical" href="https://www.example.com/blog/pro-plan-price">
<meta property="og:url" content="https://www.example.com/blog/pro-plan-price">
<meta property="og:type" content="article">
<meta property="og:title" content="We cut the Pro plan to $19 a month">
<meta property="og:description" content="What changed, who gets the new price and when it starts.">
<meta property="og:image" content="https://www.example.com/images/og/pro-plan-price-v2.jpg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Pricing card showing the Pro plan at $19 a month">
<meta property="og:site_name" content="Acme">
</head>Meta's FAQ requires absolute URLs in og:url and og:image. og:url should be the clean canonical address without tracking parameters, since likes and shares collect at that URL. Meta asks for og:title without your site name, so leave the brand to og:site_name. The -v2 in the image file name is the habit that beats the image cache.
Facebook og:image size and limits
Use a 1200 by 630 pixel image under 8 MB. Meta's image guide recommends at least that size for high-resolution screens, and the 1.91:1 ratio fills the card without cropping.
| Meta's number | Outside it | |
|---|---|---|
| Recommended size | 1200 x 630 px | Looks soft on high-resolution screens |
| Minimum for the large card | 600 x 315 px | Shown as a small square thumbnail |
| Minimum allowed | 200 x 200 px | Not accepted as the share image |
| Aspect ratio | 1.91:1 | Cropped to fit |
| File size | 8 MB | White box instead of the image |
Export a JPG or PNG of a few hundred KB and keep text away from the edges.
Common causes of broken Facebook previews
Most broken previews come down to one of four causes.
The crawler is blocked. Facebook's link crawler sends the user agent facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php). Firewall rules and CDN bot protection can stop it, and a 403 in the debugger is the usual sign. Meta says to allowlist the crawler by user agent or, more securely, by IP address. A robots.txt Disallow that matches facebookexternalhit also blocks previews, and Meta's crawlers can cache robots.txt for up to 24 hours after you fix it. On WordPress, our robots.txt for WordPress guide shows where to edit it. To keep Meta's AI training crawler out, block meta-externalagent instead. Meta documents it as a separate bot, so blocking it leaves link previews alone.
Test what your server sends that user agent:
UA="facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)"
URL="https://www.example.com/blog/pro-plan-price"
# Status code returned to Facebook's user agent
curl -s -o /dev/null -w "%{http_code}\n" -A "$UA" "$URL"
# Open Graph tags in the raw HTML
curl -s --compressed -A "$UA" "$URL" | grep -io '<meta property="og:[^>]*>'A 200 proves your server answers that user agent, not that your firewall lets Meta's IP addresses through. The debugger has the last word.
The og:image URL is relative. content="/images/share.jpg" works in a browser and fails for Facebook, which needs the full address.
The image sits behind a login. Staging sites with basic auth, private storage buckets and hotlink protection that checks the referrer all return an error to facebookexternalhit while the image loads fine for you.
JavaScript adds the tags. Single-page apps and some tag manager setups write og: tags in the browser after load. Meta's docs never say its crawler runs JavaScript, and they want the tags in the first 1 MB of the response, so render them on the server. Our AI crawler view compares raw HTML with the rendered page and flags metadata added after load.
Check your link preview tags before you scrape again
The cache refresh happens only in Facebook's own debugger. Our Open Graph checker does not refresh any platform's cached preview. It is the step before Scrape Again, so you fix every tag first and scrape once.
It fetches the page, reads every og: and twitter: tag in the <head>, downloads the share image and previews the card. It flags a missing og:title, og:description or og:image, relative or plain http image URLs, an og:url that differs from your canonical, conflicting duplicate tags, and og: tags written with name= instead of property=. For the image it checks the HTTP status, that the response is an image, the format, the 8 MB limit, the 200 by 200 minimum, the 600 px width a large card needs and the 1.91:1 ratio. If bot protection blocks the image download, the report says so, since the same rule can stop facebookexternalhit.
It reads raw HTML, so it does not see tags injected by JavaScript, and its preview approximates the card rather than matching Facebook pixel for pixel. A run costs 5 credits.