help: Nuxt 4 + nuxt-seo: `defineOgImageComponent` throws "client-only context" error

[Aravinda93]

📚 What are you trying to do?

I’m trying to use nuxt-og-image via defineOgImageComponent() on my homepage.
Even with SSR enabled and calling it at the top level of the page’s <script setup lang="ts">, I get:

500 You are using a defineOgImage() function in a client-only context.
You must call this function within your root component setup,
see https://github.com/nuxt-modules/og-image/pull/293

The same project successfully displays OG images on /docs when I use static og:image via useSeoMeta (so the Open Graph tags are functional). The issue is specifically with the generator composable on / or pages/index.vue.

---

Environment

• Nuxt: ^4.x (SSR enabled)
• @nuxtjs/seo (or nuxt-seo): latest
• Node: >=24

SSR is ssr:true. I’m not using <client-only> on the page. There is no definePageMeta({ ssr:false }) on the page.

---

Minimal Reproduction (files)

nuxt.config.ts

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: true,
  modules: [
    "@nuxtjs/i18n",
    "@nuxtjs/seo",
    "@nuxt/image",
    "@nuxt/fonts",
    "@nuxt/ui",
    "@nuxt/content",
  ],
})

layouts/default.vue:

<!-- layouts/default.vue -->
<template>
  <slot />
</template>

<script setup lang="ts">
// no defineOgImage* here
</script>

pages/index.vue:

<!-- pages/index.vue -->
<template>
  <div>Home</div>
</template>

<script setup lang="ts">
// Even with server guard and top-level call, it errors with:
// "You are using a defineOgImage() function in a client-only context"
if (import.meta.server) {
  defineOgImageComponent('NuxtSeo', {
    title: 'Test',
    description: 'Test Desc',
    theme: '#2d4d9d'
  })
}

useSeoMeta({
  title: 'Home',
  description: 'Home page',
  ogTitle: 'Home',
  ogDescription: 'Home page',
  ogImage: 'https://example.com/og/default.png', // absolute URL
  twitterCard: 'summary_large_image'
})
</script>

What I expect

The call to defineOgImageComponent('NuxtSeo', ...) to run during SSR for / (a root page component) and inject the generated og:image without error.

Nuxt DevTools → OG Image tab to show the generated image for /.

What actually happens

Navigating directly to / (hard reload) throws:

500 You are using a defineOgImage() function in a client-only context.

I am following docs to generate Nuxt OG image
References:
https://nuxtseo.com/docs/og-image/getting-started/getting-familar-with-nuxt-og-image

Question

• Why is defineOgImageComponent() considered “client-only context” even when called at the top level of a page’s <script setup> with if (import.meta.server) and SSR enabled?

• Is there any additional condition that would force this page to be treated as client-only (e.g., a subtle layout interaction or route rule) even though the page itself has no ssr:false?

• Is there a known interaction between nuxt-seo and nuxt-og-image that changes where/when the composable is allowed to run?

🔍 What have you tried?

No response

ℹ️ Additional context

No response