I shipped a fix for my broken link previews and made 65 of 66 pages worse. The build passed. Nothing warned me. The only way I found out was reading the compiled HTML.
An SVG. Facebook, X, LinkedIn and WhatsApp do not render SVG as og:image, so every link anyone shared appeared with no thumbnail at all. The declared dimensions were fiction too — a favicon is a small square, not 1200×630.
It came from a default parameter in my metadata helper that nobody had revisited:
I will not pretend this is a subtle one. It is a site whose entire pitch is "check your images before you publish them", failing at exactly that.
Next.js has a file convention for this. Drop opengraph-image.tsx in app/, export a function returning an ImageResponse, and Next generates the PNG at build time and writes the tags for you:
I added that, plus one per route for the five pages that deserved their own artwork. Removed the hardcoded image default so nothing would override the generated file. next build — clean. Route list showed the image routes being prerendered:
Before deploying I grepped the compiled HTML, which is the only reason this story has a happy ending:
Six routes had an image. Every other page had no og:image tag at all — worse than the SVG, because at least the SVG was a URL some scrapers would try.
I did not want to publish a claim I had only seen once in a messy state, so I reduced it. Branch, one file at the root, nothing else emitting images:
Then the question anyone will ask next — does a file in a segment cover that segment's children? Added app/guides/opengraph-image.tsx and rebuilt:
No. app/guides/opengraph-image.tsx covers /guides and nothing beneath it. The file applies to the one route the file sits in. Next.js 16.2.4.
The docs are not wrong here, and it is worth being precise about that. The API reference says the convention sets the image "for a route segment", and that you add the file to "any route segment". Exactly right, both times. I read straight past it, twice.
The reason it is easy to misread is that the other metadata system in App Router does cascade. A metadata object exported from a layout merges down into every page beneath it — that is the whole point of putting metadataBase, title.template and openGraph.siteName in the root layout once. So you build a mental model where "metadata set high in the tree applies to everything below", and then the file convention, which lives in the same feature area and is described on adjacent doc pages, does not behave that way.
And the failure mode is silent. A missing og:image is not an error. There is no build warning, no type error, no runtime complaint. The page renders perfectly. You find out when someone shares a link and it comes out as a grey box, which might be weeks later.
The literal fix is one opengraph-image.tsx per route segment. For this project that meant about 40 files, and doubling again for the /es subtree — plus a matching twitter-image.tsx in each, or accept that X falls back to og:image.
So instead: one static route that serves every variant, and one default in the metadata helper.
force-static plus generateStaticParams means these are prerendered at build time exactly like the file convention would be — the route handler never runs on a request. Slugs carry the extension (default.png, instagram.png) so the URL looks like an image to anything that cares.
One more detail that is easy to get wrong: keep the variant catalogue in a module that does not import next/og. If your metadata helper imports the file that imports ImageResponse, every page that reads metadata drags the renderer along with it. Catalogue and constants in one file, the ImageResponse JSX in another.