DEV Community: dziulatex

og:image not showing? How to debug it and bust each cache

dziulatex — Mon, 02 Nov 2026 10:42:28 +0000

When a shared link shows no image — or yesterday's image — the cause is almost always one of eight things, and the platform's own debugger will tell you which in a minute. The second half of the problem is caching: every platform keeps its own copy of your preview, and each one is refreshed differently. This guide covers both, in the order you should check them.

The eight usual causes

Relative URL. content="/og/post.png" works in a browser and fails in every crawler. og:image must be an absolute https:// URL.
The crawler cannot fetch the image. A login, a firewall, bot protection (Cloudflare's bot modes, security plugins), hotlink protection or a robots.txt rule blocks facebookexternalhit, LinkedInBot or Twitterbot. Note that Slack does not honour robots.txt for unfurls, so "works in Slack, not on LinkedIn" often points here.
Wrong size or file. Under 200×200 Facebook ignores the image; over 8 MB it rejects it (Meta). LinkedIn wants at least 1200×627, at most 5 MB, and lists only JPG, PNG and GIF (LinkedIn) — a WebP image can fail there while working elsewhere.
The tags are added by JavaScript. Preview crawlers read the server's HTML; a React or Vue app that sets meta tags after load shows them nothing. Render the tags on the server.
Two og:image tags. A theme and an SEO plugin both print one; the crawler takes the first, which is often the wrong one.
Your own cache serves old HTML. A page cache or CDN still returns the page from before you added the tag.
The image URL redirects badly or returns the wrong type. Long redirect chains, a 200 with an HTML error page, or Content-Type: text/plain on a PNG.
The platform's cache. Everything is fixed, but the platform shows what it fetched last week.

Step 1: see what the crawler sees

Fetch the page the way a crawler does and look at the tags:

curl -sL -A "facebookexternalhit/1.1" https://example.com/blog/post \
  | grep -Eio '<meta[^>]+(og:|twitter:)[^>]+>'

If the output has no og:image, the problem is in your HTML (causes 1, 4, 5, 6). If it does, check the image itself:

curl -sIL -A "facebookexternalhit/1.1" https://example.com/og/post.png

You want a final 200, Content-Type: image/png or image/jpeg, and a Content-Length well under 5 MB. A 403 here is cause 2; a text/html content type is cause 7.

Our free OG Checker fetches the page the way Facebook's crawler does, lists what is missing and previews the card on X, LinkedIn, Facebook, Slack and Discord; it can also scan a sitemap for pages without tags.

Step 2: ask the platform

Platform	Tool	Refreshes the cache?
Facebook, Messenger	Sharing Debugger	Yes — Scrape Again
LinkedIn	Post Inspector	Yes, for new posts (LinkedIn)
X	Paste the link into the post composer (no need to post)	No — re-crawled about weekly; change the URL
Slack	None needed	Expires after about 30 minutes (Slack)
Discord	None	Expires after about 30 minutes (Discord); or add `?v=2`
Telegram	@WebpageBot	Yes, for new messages
WhatsApp	None	No — change the URL

The Facebook debugger is the most useful diagnostic even if you do not care about Facebook: it shows the exact image it chose, its dimensions, the HTTP response code it got from your server, and a warning when the image could not be downloaded or is too small. Without a manual scrape Facebook refreshes a URL's data about every 30 days; the Graph API can trigger a re-scrape (POST /?id={url}&scrape=true), which helps when you publish many pages at once (Meta). Existing shares keep the data they were created with.

Step 3: bust the cache properly

Platforms cache two things: the page (its tags) and the image (the file behind the URL). Refreshing the page in a debugger does not always refresh the image — Meta's own advice is to "use a new URL for the new image" (Meta).

So when you change an image, change its URL:

<!-- before -->
<meta property="og:image" content="https://example.com/og/post.png">
<!-- after: a new file name or a version parameter -->
<meta property="og:image" content="https://example.com/og/post-v2.png">

Generated images get this for free if the URL depends on the content: a hash of the title in the file name, or a signed URL whose query string contains the title. Change the title and the URL changes with it. Shareglint's signed /i/ URLs and auto-OG /u/ URLs work this way — and an identical image is served from cache without a new render.

For platforms with no refresh tool (X, Discord, WhatsApp), the page URL is the cache key too. X re-crawls cards roughly every seven days and suggests sharing a changed URL to see a fix sooner (archived X docs). New posts pick up a new preview once the cached one expires; to force it now, share a URL the platform has not seen, such as https://example.com/blog/post?v=2. Do not count on previews inside messages and posts that were already sent changing; on most platforms they keep what was fetched at the time.

Framework-specific traps

Next.js: since v15.2 generateMetadata can stream its tags after the page body, but Next.js keeps them in <head> for "HTML-limited bots" such as facebookexternalhit, detected by user agent (Next.js docs). If you serve crawlers through a custom proxy or rewrite the user agent, check that they still get blocking metadata.
Single-page apps (Vite, CRA, Vue CLI): prerender the routes you want shared, or add server-side rendering for meta tags; client-side helmet libraries do not help crawlers.
WordPress: purge the page cache after changing SEO plugin settings; see automatic OG images in WordPress.
Static sites: a relative image path in front matter is the classic bug; see OG images for Hugo, Jekyll and Astro.

When the image is generated on request

If og:image points at an image that is rendered when first requested (a signed URL, next/og, your own Puppeteer endpoint), the first crawler visit pays for the render. Crawlers have short timeouts; a cold headless Chrome that needs five seconds can make the first share imageless, and the platform caches that result. Two fixes:

Warm it: after publishing, request the image once yourself (or paste the URL into the Facebook debugger) before anyone shares it.
Render ahead of time: generate the image when the post is saved and store the URL, as shown in the Laravel, Rails and Django guides.

A 60-second checklist

[ ] og:image is absolute, https://, and appears once in the server HTML.
[ ] The image returns 200, an image content type, 1200×630, under 5 MB, JPEG or PNG.
[ ] Crawlers are not blocked by a login, firewall, bot protection or hotlink rule.
[ ] og:image:width, og:image:height and twitter:card are present.
[ ] After a change: new image URL, page cache purged, Facebook Scrape Again, LinkedIn Post Inspector.

FAQ

Why is my og:image not showing on Facebook?

Usually one of: the image URL is relative, the image is smaller than 200×200 or larger than 8 MB, the crawler is blocked by a firewall or login, or Facebook cached an older version of the page. Paste the URL into the Sharing Debugger: it lists the image it found and any warnings, and Scrape Again refreshes the cache.

How do I force LinkedIn to refresh a link preview?

Inspect the URL in LinkedIn's Post Inspector, which fetches the page again; new posts then use the refreshed preview. Posts that were already published keep the old one.

How do I refresh a Telegram or WhatsApp link preview?

Telegram has an official bot, @WebpageBot: send it the URL and it updates the cached preview for new messages. WhatsApp has no refresh tool; change the image URL (for example add ?v=2) and, if needed, the page URL you share.

Do social media crawlers run JavaScript?

Link-preview crawlers such as facebookexternalhit, LinkedInBot, Twitterbot and Slackbot read the HTML the server returns and do not wait for client-side JavaScript. Meta tags added by a single-page app after load are invisible to them.

Originally published on Shareglint. Disclosure: I build Shareglint.

Next.js OG images without the @vercel/og limits

dziulatex — Mon, 02 Nov 2026 10:40:29 +0000

next/og (the ImageResponse API, built on @vercel/og) is the default way to make Open Graph images in Next.js, and for a title on a gradient it is excellent. It is not a browser, though: it converts JSX to SVG with Satori and rasterises it with Resvg. When your card needs CSS grid, your real stylesheet, woff2 fonts or more than 500 KB of assets, the fix is not to fight Satori — it is to render the card with real Chrome and put the resulting URL in generateMetadata.

This guide lists the limits precisely, shows when they bite, and gives a drop-in replacement that works on the Node.js and Edge runtimes.

The limits, from the Next.js docs

The ImageResponse reference states them plainly:

Only flexbox and a subset of CSS. "Advanced layouts (e.g. display: grid) will not work." The full list of supported properties is in Satori's README.
500 KB bundle limit, counting your JSX, CSS, fonts, images and other assets together.
Fonts: ttf, otf and woff only — no woff2, which is what most font services and next/font hand you.
Default output is 1200×630 PNG, which is the right size for Open Graph.

In practice people hit these as: a two-column card that needs grid; a brand font that only ships as woff2 (convert it, or it silently falls back); two weights of a CJK font that blow past 500 KB on their own; a logo as SVG with filters Resvg does not support; and the general cost of re-implementing a design in inline styles because the site's CSS is not available.

A note if you read Satori's own README: recent standalone Satori releases added CSS grid and WOFF2, but the @vercel/og that Next.js bundles (1.0.x in Next 16, built on an older Satori) does not have them — the Next.js limits above are the ones that apply to next/og.

None of this is a bug. Satori trades completeness for running anywhere in milliseconds. If your card fits inside it, keep it.

Option A: keep next/og, but stay inside the lines

If the limits are only fonts and size, fix those and stay with ImageResponse:

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og';
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';

export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';

// ttf/otf parse fastest; subset the font to Latin to stay far below 500 KB.
const inter = readFile(join(process.cwd(), 'assets/Inter-Bold-latin.ttf'));

export default async function Image({ params }: { params: Promise<{ slug: string }> }) {
  const post = await getPost((await params).slug);

  return new ImageResponse(
    (
      <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'space-between',
                    width: '100%', height: '100%', padding: 72, background: '#0b0a09', color: '#fff' }}>
        <div style={{ fontSize: 64, fontWeight: 700, lineHeight: 1.1 }}>{post.title}</div>
        <div style={{ fontSize: 28, opacity: 0.7 }}>yourblog.com</div>
      </div>
    ),
    { ...size, fonts: [{ name: 'Inter', data: await inter, weight: 700, style: 'normal' }] },
  );
}

Subsetting fonts (for example with pyftsubset from fonttools) is the single most effective fix for the 500 KB limit.

Option B: real Chrome, as a URL in generateMetadata

When you need grid, your stylesheet, woff2, emoji fonts or complex scripts, render the card from HTML and CSS in a real browser. Running Chrome inside a serverless function is possible (a trimmed Chromium build such as @sparticuz/chromium with puppeteer-core), but cold starts of several seconds and memory limits make it fragile — and a link-preview crawler will not wait.

The lighter option is a signed image URL: you compute it in generateMetadata (no network call, no API key on the page), and the image service renders it on the first request and serves the cached file afterwards. Below is Shareglint's URL format (disclosure: I build Shareglint) with its built-in blog-og template — swap in your own HTML template's slug to use your own design. Web Crypto makes the same code run on Node.js and Edge:

// lib/og.ts
const enc = (v: string) =>
  encodeURIComponent(v).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());

export async function ogImageUrl(template: string, fields: Record<string, string>) {
  const path = `/i/${process.env.OG_ACCOUNT_ID}/${template}.png`;
  const query = Object.keys(fields).sort().map((k) => `${enc(k)}=${enc(fields[k])}`).join('&');

  const key = await crypto.subtle.importKey(
    'raw', new TextEncoder().encode(process.env.OG_SIGNING_SECRET!),
    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
  );
  const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${path}?${query}`));
  const s = Array.from(new Uint8Array(mac), (b) => b.toString(16).padStart(2, '0')).join('').slice(0, 32);

  return `https://shareglint.com${path}?${query}&s=${s}`;
}

// app/blog/[slug]/page.tsx
import type { Metadata } from 'next';
import { ogImageUrl } from '@/lib/og';

export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
  const post = await getPost((await params).slug);
  const image = await ogImageUrl('blog-og', { title: post.title, author: post.author, site: 'yourblog.com' });

  return {
    title: post.title,
    openGraph: { images: [{ url: image, width: 1200, height: 630, alt: post.title }] },
    twitter: { card: 'summary_large_image', images: [image] },
  };
}

encodeURIComponent leaves ! ' ( ) * unescaped, which RFC 3986 does not — the replace fixes that so the signature matches. We checked this function against the test vector in the API docs. OG_SIGNING_SECRET has no NEXT_PUBLIC_ prefix, so Next.js never inlines it into client bundles; only the signature ends up in the HTML.

Two Next.js details to know:

File conventions win. If a route segment has an opengraph-image.tsx or .png, Next.js uses it instead of openGraph.images from generateMetadata — the generateMetadata docs say file-based metadata "has the higher priority and will override" both. Delete the file when you switch.
Absolute URLs. A signed URL is already absolute. If you keep any relative image paths, set metadataBase in the root layout or Next.js cannot build the full URL.

Option C: render at build time for static exports

With output: 'export' there is no server at request time. A signed URL still works — it is a string computed during the build. If you would rather ship files, call the API from a build script and store the returned URLs:

// scripts/og-images.ts — run before `next build`
const res = await fetch('https://shareglint.com/v1/images?wait=true', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.OG_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ template: 'blog-og', modifications: { title: post.title, site: 'yourblog.com' } }),
});
const { url } = await res.json();   // same fields again = same file, no extra render

Which to choose

You need	Use
Title, logo, gradient; fonts under 500 KB	`next/og`
CSS grid, your own stylesheet, woff2, complex scripts	Real Chrome — signed URL (B)
No server at all (`output: 'export'`)	Signed URL computed at build, or a build script (C)
One generic card for every page	A static `opengraph-image.png`

Whichever you pick, verify the result where it is seen: paste a production URL into LinkedIn's Post Inspector and Facebook's Sharing Debugger — localhost URLs cannot be fetched by either.

FAQ

What are the limits of next/og ImageResponse?

According to the Next.js docs: only flexbox and a subset of CSS (no display: grid), a 500KB bundle limit including JSX, CSS, fonts and images, and only ttf, otf and woff fonts. It renders with Satori and Resvg, not a browser.

Can I use Tailwind or my existing React components in an OG image?

Only partly with next/og: Satori accepts inline styles and a tw prop, but not your stylesheet, CSS grid or arbitrary components. A renderer that runs real Chrome takes ordinary HTML and CSS, so the card can share your design system.

Does opengraph-image.tsx override generateMetadata?

Yes. Next.js gives file-based metadata higher priority than config-based metadata, so an opengraph-image file in a route segment replaces the openGraph.images you return from generateMetadata.

Do I need the Edge runtime for OG images?

No. ImageResponse works on both the Node.js and Edge runtimes, and a signed image URL is just a string you compute — Web Crypto makes the same code work on either.

Originally published on Shareglint.

What is an Open Graph image? Tags, platforms and fixes

dziulatex — Mon, 02 Nov 2026 10:36:23 +0000

An Open Graph image (OG image) is the picture a link shows when it is shared on LinkedIn, Facebook, X, Slack, Discord, WhatsApp or iMessage. You set it with one tag in the page's <head> — <meta property="og:image" content="https://example.com/og/post.png"> — and each platform's crawler downloads it the first time the link is shared. The size that works everywhere is 1200×630 pixels, as JPEG or PNG under 600 KB; the per-platform table has every documented limit.

The minimal tag set to copy

Paste this into the <head> of every page, with that page's own values:

<meta property="og:title" content="How we cut our image pipeline to 900 ms">
<meta property="og:description" content="Moving rendering off the request path and caching by content hash.">
<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/blog/image-pipeline">
<meta property="og:image" content="https://example.com/og/image-pipeline.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Title card: How we cut our image pipeline to 900 ms">
<meta name="twitter:card" content="summary_large_image">

Why each line is there:

Tag	What it does
`og:title`, `og:type`, `og:url`, `og:image`	The four properties the Open Graph protocol calls required
`og:description`	The line under the title; LinkedIn and WhatsApp list it as required
`og:image:width`, `og:image:height`	Lets Facebook "render the image immediately without having to asynchronously download and process it" (Meta); Discord otherwise downloads the image just to measure it
`og:image:alt`	A description of the image, "not a caption"; ogp.me says a page with `og:image` should set it
`twitter:card`	Chooses X's card layout; `summary_large_image` is the big image above the title

Open Graph uses property=, Twitter Cards use name=. Most parsers accept either, but following each spec avoids surprises.

How each platform reads it

When a link is pasted, the platform fetches the page's HTML, reads the tags, then fetches the image from its own servers. Apple states that Messages runs no JavaScript, and no other platform documents running it, so treat the HTML your server sends as all they see. What each one documents:

Facebook (crawler facebookexternalhit) lists og:url, og:title, og:description and og:image as the basic tags (Meta), and the Open Graph properties must come before the first 1 MB of the page (Meta crawlers).
LinkedIn says og:title, og:image, og:description and og:url "must exist" (LinkedIn Help).
X reads its own twitter: tags and falls back to og:title, og:description and og:image when one is missing. Without twitter:card, "a summary card may be rendered" — the small one with a square image (X cards markup, archived).
Slack (Slackbot-LinkExpanding) reads oEmbed, Twitter Card and Open Graph tags and caches the result for "around 30 minutes" (Slack). It does not honour robots.txt for unfurls.
Discord reads og: and twitter: tags and theme-color for the accent bar, shows a small image unless twitter:card is summary_large_image, and gives the page 10 seconds (Discord).
WhatsApp needs og:title, og:description, og:url and an absolute og:image under 600 KB, with the <head> inside the first 300 KB of HTML (Meta).
iMessage reads Open Graph tags, follows server redirects but not JavaScript ones, and wants images at least 900 px wide (Apple TN3156).

Two rules follow for developers: the tags must be in the HTML the server sends, and the image URL must be absolute and public — the crawler fetches it without your cookies.

og:image vs twitter:image

X has its own tags (Twitter Cards). twitter:card picks the layout, twitter:image the picture, twitter:title and twitter:description the text. The last three fall back to their Open Graph counterparts; twitter:card falls back only to the small summary card. So the usual set is og:image plus one line:

<meta name="twitter:card" content="summary_large_image">

Set twitter:image only when X should get a different picture from everyone else. The large card is 2:1 and the plain summary card crops the image to a square, so 1200×630 suits summary_large_image, not summary.

Common failures, and how to see them

Six common causes, each with a way to see it:

Relative image URL. content="/og/post.png" works in a browser, not everywhere else: WhatsApp asks for an absolute URL, and Discord accepts a relative one only when it starts with /. Write the scheme and host every time.
The image answers 404, 403 or a redirect to a login page. The crawler is anonymous. Open the image URL in a private window; if you see anything but the image, so does the crawler. Hotlink protection and bot-blocking firewalls cause the same symptom.
Tags added by JavaScript. A single-page app that sets meta tags after load risks showing nothing: Messages runs no scripts, and no other platform says it does. Render the tags on the server or at build time.
Wrong size or file. Under 600×315 Facebook shows a small image; under 401 px wide LinkedIn shows a thumbnail; WhatsApp asks for under 600 KB. The size reference lists each platform's limits and has an in-browser check.
Tags too far down the page. Facebook reads Open Graph properties only in the first 1 MB, WhatsApp the first 300 KB. Put them near the top of <head>, before large inline scripts or styles.
The old preview is cached. Fixing the tag does not change a card that was already fetched. Facebook caches images by URL, so give a new image a new URL and re-scrape the page in the Sharing Debugger. LinkedIn's Post Inspector refreshes its preview. Slack and Discord keep previews for about 30 minutes; X documents no refresh tool.

To see all of this at once, paste the page into the free OG Checker: it fetches the page like a crawler, lists missing or broken tags and previews the card on X, LinkedIn, Facebook, Slack and Discord. The debugging guide goes through each platform step by step.

What makes a good OG image

The image is shown at a few hundred pixels wide in a feed and smaller in chat apps, next to your title in plain text. So:

Large type, few words. A title set at 60–80 px on a 1200-px canvas stays readable when scaled down; body-size text does not. Apple advises against text in preview images altogether, because Messages shows them at varying sizes.
Keep it away from the edges. X's large card is 2:1, and how it crops other ratios is not documented. Keep the title and logo inside the middle 1200×600.
Brand consistently. A logo or colour bar in the same place on every card makes your links recognisable in a busy feed.
Small files. Our own 1200×630 text cards come out at 55–60 KB as JPEG; whatever you use, stay under WhatsApp's 600 KB.

How sites produce one image per page

A single site-wide image is fine for a homepage; for articles, products, docs pages and job posts, a per-page image with that page's title works better. The common ways to make them:

By hand in a design tool — fine for a handful of pages.
At build time or in a job, with a headless browser (Puppeteer, Playwright) or a drawing library (Pillow, GD, Satori/next/og). Free per image, but you maintain the renderer, fonts and memory.
With an image API: you keep a template and send the page's fields, from your server or as a signed URL right in the og:image tag. Shareglint (disclosure: I build it) is one of these: 153 built-in 1200×630 templates, your own HTML and CSS, and a Free plan of 100 images a month — the API docs show the request. Others include Bannerbear, Placid and HTMLCSStoImage; see the comparison.
With a screenshot of the page itself — quick, but a desktop screenshot is the wrong shape and hard to read at thumbnail size; when screenshots make sense.

Framework walkthroughs: Next.js, Laravel, Rails, Django, WordPress and static sites.

FAQ

What is an OG image?

The image set in a page's og:image meta tag. Social networks and messaging apps show it in the preview card when someone shares a link to the page, next to the title and description from og:title and og:description.

Is og:image required?

The Open Graph protocol lists og:image among its four required properties, with og:title, og:type and og:url, and LinkedIn and WhatsApp both list it among the tags a preview needs. Without it most platforms show a text-only preview.

What size should an OG image be?

1200×630 pixels (1.91:1), JPEG or PNG, under 600 KB. That meets Facebook's recommendation, LinkedIn's 1200×627 minimum, X's card limits and WhatsApp's 600 KB limit.

What is the difference between og:image and twitter:image?

og:image comes from the Open Graph protocol and is read by almost every platform. twitter:image is X's own tag; X uses it when present and falls back to og:image when it is missing. Set twitter:card to summary_large_image too: without it X may render the small summary card.

Why does my old OG image still show?

Platforms cache previews. Facebook caches images by URL, so give a new image a new URL and re-scrape in the Sharing Debugger; LinkedIn's Post Inspector refreshes a preview; Slack and Discord keep one for about 30 minutes.

Originally published on Shareglint.

Built an API that translates text to Gen Z slang (works in any language)

dziulatex — Sat, 25 Oct 2025 22:23:45 +0000

Made a simple API that converts normal sentences into Gen Z slang using Claude AI.

Example:
"I'm having a great day" → "Today hits different fr fr, got that W energy no cap 💯"

Tech: Symfony + Claude AI + 40-term slang dictionary

Cool part: Works in multiple languages automatically - just one prompt rule made it multilingual.

Built it for fun but now it's on RapidAPI. Thinking of adding "slang intensity levels" next.

Drop a sentence and I'll convert it for you 👇

[Link if interested: https://rapidapi.com/dziulatex/api/boomer-language-to-genz-slang]