Troubleshooting Nuxt Sitemap

Last updated Oct 13, 2026Harlan Wilton

Debugging

Nuxt DevTools. The best tool for debugging is the Nuxt DevTools integration with Nuxt Sitemap. This will show you all of your sitemaps and the sources used to generate them. The panel needs the nuxtseo-devtools-host package as a dev dependency. Install it with pnpm add -D nuxtseo-devtools-host, then restart the dev server.

Debug endpoint. If you prefer looking at the raw data, you can use the debug endpoint. This is only enabled in development unless you enable the debug option. Visit /__sitemap__/debug.json within your browser. This is the same data used by Nuxt DevTools.

Debugging prerendering. If you're trying to debug the prerendered sitemap, you should enable the debug option and check your output for the file .output/public/__sitemap__/debug.json.

Submitting an Issue

When submitting an issue, it's important to provide as much information as possible.

The easiest way to do this is to create a minimal reproduction using the Stackblitz playgrounds:

Troubleshooting FAQ

Why is my browser not rendering the XML properly?

When disabling the XSL (XML Stylesheet), the XML will be rendered by the browser.

If you have an i18n integration, then it's likely you'll see your sitemap look raw text instead of XML.

Broken XML because of xhtml namespace.

This is a browser bug in parsing the xhtml namespace which is required to add localized URLs to your sitemap. There is no workaround besides re-enabling the XSL.

Google Search Console shows Error when submitting my Sitemap?

Open the sitemap row in Search Console and read the reported error. XML validation checks structure. It does not prove Google can fetch the deployed file. Follow Google's Sitemaps report guidance.

Google Search Console shows "Couldn't fetch" or "Sitemap could not be read"?

Google could not retrieve the sitemap. Check the exact submitted URL, robots.txt rules, authentication requirements, and server responses. Some failures are temporary. Check later fetch attempts to see whether Google can retrieve the sitemap.

Open the sitemap row and expand its error details.
Copy the submitted URL into Search Console's URL Inspection tool.
Run Live test and expand Page availability.
Check that Crawl allowed? is Yes and Page fetch is Successful.

A successful live test shows current fetch access. It does not prove the previous failure was a cache issue. Validate the returned XML separately.

If fetch or parsing errors persist, fix the reported cause and resubmit the sitemap. Google retries failed fetches for a few days and can stop trying after continued failures.

Processing a sitemap does not prove its URLs are indexed. Google Search timelines separates sitemap processing, page crawling, and indexing. Reported timings do not establish a deadline for your sitemap.

If you need a different sitemap URL, set sitemapName:

nuxt.config.ts

export default defineNuxtConfig({
  sitemap: {
    sitemapName: 'sitemap_index.xml',
  },
})

After deploying, test the new URL and submit it in Search Console. Renaming does not guarantee a fresh fetch or resolve server and access failures.

Use the XML Sitemap Validator to check structure. A valid result does not establish why Google could not fetch the file.

Getting 404/Error when Pinging Google?

If you are using a script or CI/CD job to "ping" Google with your sitemap URL (e.g., google.com/ping?sitemap=...), it will now fail.

Google deprecated the sitemap ping endpoint in January 2024. You should remove this step from your deployment process and rely on robots.txt discovery or Google Search Console.

Search Console shows "Invalid character" error?

This happens when URLs contain reserved characters like $, :, or @ that aren't properly encoded for XML.

The module automatically encodes unicode characters (emojis, accents) but does not encode RFC-3986 reserved characters.

Solution: If your API returns pre-encoded URLs, mark them with _encoded: true to prevent double-encoding:

server/api/__sitemap__/urls.ts

export default defineSitemapEventHandler(async () => {
  const urls = await $fetch('https://api.example.com/pages')
  // URLs are already encoded: [{ path: '/products/%24pecial' }]

  return urls.map(url => ({
    loc: url.path,
    _encoded: true,
  }))
})

See Handling Pre-Encoded URLs for more details.

Build fails with `defineAppConfig is not defined`?

On Nuxt 4.6 with future.compatibilityVersion: 5, sitemap 9.0.0 to 9.0.2 fail at prerender when app.config.ts calls defineAppConfig():

ERROR  defineAppConfig is not defined

Compatibility version 5 turns Nitro auto-imports off. Those releases call nuxt/server request helpers that pull app.config.ts into the server bundle, and nothing defines defineAppConfig there.

Solution: Upgrade to @nuxtjs/sitemap 9.0.3 or later. If you cannot upgrade, turn Nitro auto-imports back on:

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    nitroAutoImports: true,
  },
})

Your own server code can cause the same error if it calls getRequestHost(), getRequestURL() or useAppConfig() from nuxt/server while the server starts. The same setting fixes that too.