Troubleshooting

Debugging Tools

Use these free tools to diagnose SEO issues:

• Meta Tag Checker - Validate title and description
• Social Share Debugger - Debug OG images
• Robots.txt Generator - Test robots rules
• Schema.org Validator - Validate structured data
• XML Sitemap Validator - Check sitemap structure

Have a question about Nuxt SEO? Check out the frequently asked questions below or Jump in the Discord and ask me directly.

Setup Checks

In nuxt dev, the first successful home page response starts a background check across every installed module. The terminal then reports what is missing.

• Required checks find setup that breaks SEO output. Each one names the fix, the reason, and a docs link. They report once per server start.
• Tips suggest optional features that fit your app. They report at most once every seven days per project.

Required checks cover:

• Site Config: a production site.url and a site.name.
• Robots: no robots.txt validation errors.
• Sitemap: an absolute site URL, and no failing sitemap sources.
• OG Image: an installed renderer. If OG Image signs URLs, also a NUXT_APP_SECRET for production.

The Nuxt SEO DevTools panel shows the same checklist, with a refresh action. CI and AI agent sessions skip the terminal report. Production builds run no check.

To hide tips but keep required checks, set tips to false:

export default defineNuxtConfig({
  nuxtseo: { tips: false },
})

The tips cooldown lives in .nuxt/cache/nuxt-seo/setup-tips.json. Delete that file to show tips again. In development, /__nuxt-seo__/setup.json returns the setup data that DevTools reads.

Troubleshooting FAQ

Should I use @nuxtjs/seo or the individual modules?

@nuxtjs/seo installs all 9 modules at once. It also checks module versions at build time, and runs setup checks in development. You get the exact same modules, features, and configuration options either way.

Use @nuxtjs/seo for convenience. Install modules individually if you only need a few of them or want version pinning control.

See the Introduction for more details.

Can I use the modules separately? Yes! Nuxt SEO is designed to be flexible and work however you need it to.

Do I need to install nuxt-site-config separately? No. nuxt-site-config installs automatically when you install any Nuxt SEO module (whether via @nuxtjs/seo or individually). You never need to add it to your modules array.

How do I set up Nuxt Content with multiple SEO modules? Use each module's defineXxxSchema() function in your content.config.ts. Only include schemas for the modules you use.

See the Nuxt Content guide for the full setup.

Why does my production build go up so much?

Server-side features add 2-5MB to the production build but don't affect client-side runtime performance since most module logic runs on the server.

If the production build size is a concern, you can disable the modules you don't need.

If you are using Nuxt SEO in a serverless environment, you may want to keep your workers under 1MB. The module that will contribute the most to your worker size is nuxt-og-image.

Options:

1. Disable it: ogImage: { enabled: false }
2. Use Zero Runtime mode (build-time generation)

What happened to Nuxt SEO Kit?

The Nuxt SEO Kit module was the initial version of Nuxt SEO.

While it generally worked great for some users, it was only useful for server-side generated Nuxt Sites and in turn its feature set was much more limited.

It has been deprecated in favor of the new Nuxt SEO module.

See the migration guide for more information.

Create a reproduction: when filing issues, include a minimal reproduction. See Debugging Modules for StackBlitz playgrounds.