How to make an Open Graph image accessible to social crawlers
Make social link previews find the right image: add Open Graph tags, check crawler access, and debug missing previews step by step.
To make an Open Graph image accessible to social crawlers, put a fully qualified image URL in og:image within the shared page’s delivered <head>, allow crawlers to fetch both the page and image, and validate the result with the social platform’s current preview debugger. Add og:image:alt describing the image. The Open Graph protocol does not set one universal image size or format limit for every platform, so check each platform’s current official guidance.
1. Add complete Open Graph metadata
The Open Graph protocol’s four required properties are og:title, og:type, og:image, and og:url. The tags belong in the document head. Use an absolute HTTPS URL for the image so the crawler can identify the resource without resolving a relative path.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Release notes | Example</title>
<meta property="og:title" content="Release notes">
<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/releases/1-4">
<meta property="og:image" content="https://example.com/assets/release-1-4.webp">
<meta property="og:image:alt" content="A diagram of the new release workflow">
<meta property="og:image:secure_url" content="https://example.com/assets/release-1-4.webp">
<meta property="og:image:type" content="image/webp">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
</head>
<body>
<h1>Release notes</h1>
</body>
</html>The width and height above are illustrative metadata values, not recommended or universally accepted dimensions. Use values that describe the actual image. Check the social service’s official documentation for accepted dimensions, formats, byte limits, aspect ratios, and cropping behavior.
What the image fields mean
| Property | Purpose | Guidance |
|---|---|---|
og:image |
Identifies the image resource. | Use the intended publicly fetchable image URL. |
og:image:alt |
Describes image contents for accessibility. | Describe what the image shows; do not use it as a caption. |
og:image:secure_url |
Provides an alternate secure image URL. | Useful when specifying an HTTPS alternative. |
og:image:type |
States the image MIME type. | Match the actual served file type. |
og:image:width and og:image:height |
Describe image pixel dimensions. | Report the actual dimensions; these fields do not establish platform requirements. |
The protocol says a page that specifies og:image should also specify og:image:alt. Provide a concise description that conveys the image’s content.
2. Ensure the crawler can read the page and image
Open Graph metadata is HTML. Put it in the head of the response delivered for the shared URL. For a JavaScript application, inspect the raw HTTP response as well as the browser-rendered page. A tag inserted only after client-side JavaScript runs may not be visible to every crawler.
- Open the exact shared URL without being logged in and inspect its returned HTML. Confirm the expected title, canonical share URL, and image tag are present in the head.
- Open the exact image URL from a public, unauthenticated context. Confirm it resolves to the intended image and does not require a login, short-lived token, particular location, or human-only challenge.
- Review
robots.txtrules that apply to the relevant crawler’s user agent for both the page path and image path. - Check any access controls, CDN rules, hotlink protection, or firewall rules that could prevent a crawler from fetching either resource.
- Run the page through the social platform’s current official preview or debugger and inspect what it parsed and fetched.
RFC 9309 says crawlers must follow parseable robots.txt rules when they successfully download the file. It also states, “These rules are not a form of access authorization.” Robots rules are crawler guidance, not a way to secure private images. The RFC distinguishes a robots.txt response in the 4xx range from a 5xx or network failure; crawler implementations may have their own details. See the [Open Graph protocol](https://ogp.me/) and [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309).
3. Handle multiple images and metadata correctly
A page can declare more than one og:image. The protocol says that where values conflict, the first value from top to bottom is preferred. Put the desired primary image first, then its structured properties, before declaring another image.
<meta property="og:image" content="https://example.com/assets/primary.webp">
<meta property="og:image:alt" content="The primary release illustration">
<meta property="og:image:type" content="image/webp">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image" content="https://example.com/assets/alternate.jpg">
<meta property="og:image:alt" content="An alternate release illustration">
<meta property="og:image:type" content="image/jpeg">Keep each image’s associated structured fields immediately after its root image declaration. This makes the intended association and ordering clear to parsers.
4. Validate the social preview
- Publish the metadata and image at stable, public URLs.
- Check the delivered page HTML and fetch the image URL independently.
- Use the target platform’s official sharing preview or debugger, where available. Confirm which image it selected and whether it could fetch it.
- After fixing a problem, request a fresh preview in the platform tool if it supports that action. A previously generated preview may be cached.
Preview tools, refresh controls, and cache behavior differ by platform and can change. Follow the current official instructions for the service where the link will be shared; do not assume one debugger or refresh action works everywhere.
5. Troubleshoot missing or incorrect images
| Symptom | Likely cause | What to check or fix |
|---|---|---|
| No image in preview | The tag is missing, malformed, outside the head, or absent from the delivered HTML. | Inspect the response HTML for a valid property="og:image" tag with a complete URL. |
| Image works in your browser, crawler cannot fetch it | Authentication, expiring URL, geographic restriction, challenge page, firewall, or hotlink rule. | Test the exact URL unauthenticated and remove access requirements for the share image. |
| Old image still appears | The platform may be showing a cached preview. | Use the platform’s current debugger or preview tool to refresh or inspect the shared URL, if supported. |
| Wrong image selected | Multiple image tags exist and another one appears first. | Put the intended image first and keep its structured fields adjacent. |
| Page has metadata in the browser but preview misses it | Metadata may be inserted only after client-side JavaScript runs. | Serve the tags in the HTML response or use server-side rendering; verify the raw response. |
| Image is rejected or cropped unexpectedly | Format, dimensions, aspect ratio, file size, or crop behavior may not meet that platform’s rules. | Consult that platform’s current official image guidance and prepare a compatible asset. |
| Only some crawlers fail | Robots rules or infrastructure behavior may differ by user agent. | Review applicable robots groups and access logs, then check CDN, firewall, and challenge rules. |
6. Performance and reliability considerations
- Serve a stable image URL. Avoid URLs that expire or depend on a user session; a shared preview may be fetched after the page is published.
- Keep the image available with the page. A page that loads while its image host is unavailable can still produce a missing preview.
- Make metadata server-visible. Emitting tags in the initial HTML avoids depending on crawler support for client-side rendering.
- Use accurate fields. Incorrect type or dimension metadata can confuse debugging and may conflict with the actual resource.
- Plan for caching. A corrected page may not immediately change a platform’s existing preview. Use its documented refresh procedure, when available.
- Do not rely on robots.txt for privacy. It does not authenticate or protect an asset; use real access controls for private resources, and do not put private URLs in public metadata.
7. Capture a candidate image from a page
If you still need to create the image, a browser screenshot can help produce a candidate asset. A screenshot is not a substitute for checking platform-specific requirements: inspect and resize or redesign the resulting file as needed, then host it at a public stable URL and point og:image to that URL.
DIY with Playwright
This runnable Node.js example captures a page as a PNG. Install Playwright and its Chromium browser first with npm install playwright and npx playwright install chromium.
// save as capture.mjs
import { chromium } from 'playwright';
const url = process.argv[2] ?? 'https://example.com';
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage({ viewport: { width: 1200, height: 630 } });
await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
await page.screenshot({ path: 'og-candidate.png', type: 'png' });
console.log('Saved og-candidate.png');
} finally {
await browser.close();
}Run it with node capture.mjs https://example.com. The viewport is a capture choice, not a universal social platform requirement. Review the image and consult the target service’s current guidance before publishing.
Check the published tags with cURL
curl -fsSL https://example.com/releases/1-4Inspect the returned HTML for the Open Graph tags. Fetch the image itself separately to confirm the public URL returns the intended asset:
curl -fL https://example.com/assets/release-1-4.webp -o downloaded-image.webpCheck metadata with Python
import requests
from bs4 import BeautifulSoup
url = "https://example.com/releases/1-4"
response = requests.get(url, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, "html.parser")
for name in ("og:title", "og:type", "og:url", "og:image", "og:image:alt"):
tag = soup.find("meta", attrs={"property": name})
print(f"{name}: {tag.get('content') if tag else 'MISSING'}")Install dependencies with python -m pip install requests beautifulsoup4. This checks the HTML returned to the script; it does not emulate a platform crawler or validate platform-specific image rules.
Check metadata with Node.js
// Node.js 18+
const response = await fetch('https://example.com/releases/1-4');
if (!response.ok) throw new Error(`Page request failed: ${response.status}`);
const html = await response.text();
for (const name of ['og:title', 'og:type', 'og:url', 'og:image', 'og:image:alt']) {
const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const match = html.match(new RegExp(`]*property=["']${escaped}["'][^>]*content=["']([^"']*)`, 'i'));
console.log(`${name}: ${match?.[1] ?? 'inspect HTML manually'}`);
} HTML attribute order and quoting can vary, so treat this small check as a convenience and inspect the response directly if it does not find a tag.
8. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. Its clean capture flow accepts cookie or consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response reports the page verdict and billing status in headers. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
For an image candidate, capture the target page, then review the resulting file, adapt it to the platform’s current image guidance, host it publicly, and set its URL as og:image.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for the request options. 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.
FAQ
Does Open Graph require a particular image size?
No. The protocol defines image metadata fields but does not prescribe one universal size, format, or byte limit. Consult the current official guidance for each platform where you share links.
Should I use an absolute URL for og:image?
Yes, it is the robust deployment choice. Use a complete public HTTPS URL so crawlers can request the resource directly.
Does a robots.txt allow rule guarantee the image is publicly accessible?
No. Robots.txt supplies crawler rules; it is not access authorization. The image must also be reachable under the host’s actual access and network rules.
Why does the preview still show the old image after I changed the tag?
The service may have cached the preview. Check its current debugger or sharing tool for a way to inspect or refresh the cached result.
