Next.js Open Graph image not working

Most Next.js preview bugs come from the Metadata API: a missing metadataBase, an openGraph object that replaces the parent one, or an image file over the limit.

Last updated

Check your URL

Refresh preview

Generate tags

Quick fix

  1. Set metadataBase in the root layout so relative image paths become absolute URLs.

  2. Repeat the full openGraph object in any page that overrides it.

  3. Keep opengraph-image under 8 MB and twitter-image under 5 MB.

  4. Check the deployed URL with the meta tag checker, not localhost.

Why the Next.js preview is missing or wrong

  • Relative image paths without metadataBase. A relative URL in a URL-based metadata field without metadataBase causes a build error, and platforms can’t fetch relative paths anyway.

  • A page overrides openGraph and loses the image. Metadata from layouts and pages is merged shallowly, so a page’s openGraph object replaces the layout’s whole openGraph, image included.

  • The image file is too large. opengraph-image must be under 8 MB and twitter-image under 5 MB, or the build fails.

  • You tested on localhost or a protected preview deployment. Platforms fetch from their own servers and can’t reach it.

  • The platform cached an earlier deploy. Refresh it after the fix.

How to fix it

  1. In app/layout.tsx, set metadataBase: new URL('https://your-domain.com').

  2. When a page sets openGraph, include images again, or spread the parent images from generateMetadata.

  3. Or add an opengraph-image.png file to the route segment. Next.js adds og:image, its type, width and height for you.

  4. For generated images, use ImageResponse from next/og with size = { width: 1200, height: 630 }.

  5. Deploy, then check the public URL with the meta tag checker.

Tags Next.js should output

  • og:title, og:description, og:url

  • og:image with og:image:width, og:image:height and og:image:type

  • og:image:alt from opengraph-image.alt.txt

  • twitter:card and twitter:image (absolute URL)

You can write these by hand with the meta tag generator and compare them with your build.

Image size rules

  • opengraph-image: .jpg, .jpeg, .png or .gif, max 8 MB

  • twitter-image: same types, max 5 MB

  • 1200 x 630 px is the size Next.js uses in its examples

Streaming metadata and crawlers

Newer Next.js versions can stream metadata from generateMetadata into the body. For HTML-limited bots such as facebookexternalhit, Next.js still blocks rendering and puts the tags in the head. It detects these bots by user agent. You can override the list with htmlLimitedBots in next.config.

How to force a refresh

Next.js can’t clear another platform’s cache. After deploying, refresh each platform: Post Inspector for LinkedIn, the Sharing Debugger for Facebook, a new query string for X, Slack and Discord. The refresh tool has all of them.

Sources

FAQ

Why is my Next.js og:image a relative URL?

metadataBase isn’t set. Set it in the root layout so Next.js turns relative paths into absolute URLs.

Why does my page lose the og:image from the layout?

Next.js merges metadata shallowly. If a page defines openGraph, it replaces the layout’s openGraph object, so add images again in the page.

What is the file size limit for opengraph-image in Next.js?

8 MB for opengraph-image and 5 MB for twitter-image. Larger files fail the build.

Check your page, then refresh the preview

Paste your URL into the free checker to see the exact tags each app reads. Once the tags are right, use the refresh tool to clear the old preview.

Check your URL

Refresh preview

Generate tags

Related guides

X (Twitter) card not showing or not updating

X builds the card from twitter: tags, falling back to og: tags. There is no longer a validator that refreshes the cache, so the fix is good tags plus a fresh URL.

Framer social preview not updating

Framer sets a site-wide social preview, page overrides and per-item CMS images. If the new image is live but the old one still shows, the platform’s cache is the cause.

Webflow Open Graph image not working

Webflow sets Open Graph per page, never globally. CMS template pages need an Image field, and every image in that collection must share the same size.