Troubleshooting Nuxt Sitemap

Last updated Dec 17, 2025 by Harlan Wilton in feat: mark entries as pre-encoded `_encoded: true` Fixes #473.

Copy for LLMs

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 it.

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) in, the XML will be rendered by the browser.

If you have a 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 localised URLs to your sitemap. There is no workaround besides re-enabled the XSL.

Google Search Console shows Error when submitting my Sitemap?

Seeing "Error" when submitting a new sitemap is common. This is because Google previously crawled your site for a sitemap and found nothing.

If your sitemap is validating correctly, then you're all set. It's best to way a few days and check back. In nearly all cases, the error will resolve itself.

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,
  }))
})