Troubleshooting Nuxt Sitemap · Nuxt Sitemap · Nuxt SEO [NuxtSEO](https://nuxtseo.com/ "Home") - [Modules](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction) - [Tools](https://nuxtseo.com/tools) - [Pro](https://nuxtseo.com/pro) - [Learn SEO](https://nuxtseo.com/learn-seo/nuxt) [Releases](https://nuxtseo.com/releases) [1.4K](https://github.com/harlan-zw/nuxt-seo) [Nuxt SEO on GitHub](https://github.com/harlan-zw/nuxt-seo) [User Guides](https://nuxtseo.com/docs/sitemap/getting-started/introduction) [API](https://nuxtseo.com/docs/sitemap/api/config) [Releases](https://nuxtseo.com/docs/sitemap/releases/v8) Sitemap - [Switch to Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction) - [Switch to Nuxt SEO](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction) - [Switch to Robots](https://nuxtseo.com/docs/robots/getting-started/introduction) - [Switch to OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction) - [Switch to Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction) - [Switch to Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction) - [Switch to SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction) - [Switch to Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction) - [Switch to Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction) - [Switch to AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction) Search…```k`` /` v8.0.13 - Playgrounds - [Discord Support](https://discord.com/invite/275MBUBvgP) ### Getting Started - [Introduction](https://nuxtseo.com/docs/sitemap/getting-started/introduction) - [Installation](https://nuxtseo.com/docs/sitemap/getting-started/installation) - [Data Sources](https://nuxtseo.com/docs/sitemap/getting-started/data-sources) - [Troubleshooting](https://nuxtseo.com/docs/sitemap/getting-started/troubleshooting) ### Core Concepts - [Dynamic URL Endpoints](https://nuxtseo.com/docs/sitemap/guides/dynamic-urls) - [Disabling Indexing](https://nuxtseo.com/docs/sitemap/guides/filtering-urls) - [Multi Sitemaps](https://nuxtseo.com/docs/sitemap/guides/multi-sitemaps) - [I18n](https://nuxtseo.com/docs/sitemap/guides/i18n) - [Nuxt Content](https://nuxtseo.com/docs/sitemap/guides/content) - [Nuxt Prerendering](https://nuxtseo.com/docs/sitemap/guides/prerendering) - [Best Practices](https://nuxtseo.com/docs/sitemap/guides/best-practices) - [Submitting Your Sitemap](https://nuxtseo.com/docs/sitemap/guides/submitting-sitemap) - [Zero Runtime](https://nuxtseo.com/docs/sitemap/guides/zero-runtime) ### Advanced - [Lastmod, Priority, and Changefreq](https://nuxtseo.com/docs/sitemap/advanced/loc-data) - [Images, Videos, News](https://nuxtseo.com/docs/sitemap/advanced/images-videos) - [Sitemap Performance](https://nuxtseo.com/docs/sitemap/advanced/performance) - [Sitemap Chunking](https://nuxtseo.com/docs/sitemap/advanced/chunking-sources) - [Customising the UI](https://nuxtseo.com/docs/sitemap/advanced/customising-ui) Getting Started # Troubleshooting Nuxt Sitemap [Copy for LLMs](https://nuxtseo.com/docs/sitemap/getting-started/troubleshooting.md) ## [Debugging](#debugging) ### [Nuxt DevTools](#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](#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](#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](#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: - [Dynamic URLs](https://stackblitz.com/edit/nuxt-starter-dyraxc?file=server%2Fapi%2F_sitemap-urls.ts) - [i18n](https://stackblitz.com/edit/nuxt-starter-jwuie4?file=app.vue) - [Manual Chunking](https://stackblitz.com/edit/nuxt-starter-umyso3?file=nuxt.config.ts) - [Nuxt Content Document Driven](https://stackblitz.com/edit/nuxt-starter-a5qk3s?file=nuxt.config.ts) ## [Troubleshooting FAQ](#troubleshooting-faq) ### [Why is my browser not rendering the XML properly?](#why-is-my-browser-not-rendering-the-xml-properly) When disabling the [XSL](https://nuxtseo.com/docs/sitemap/advanced/customising-ui#disabling-the-xls) (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.](https://nuxtseo.com/docs/sitemap/formatting-error.png) This is a [browser bug](https://bugs.chromium.org/p/chromium/issues/detail?id=580033) 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?](#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](https://www.xml-sitemaps.com/validate-xml-sitemap.html) correctly, then you're all set. It's best to wait a few days and check back. In nearly all cases, the error will resolve itself. ### [Google Search Console shows "Couldn't fetch" or "Sitemap could not be read"?](#google-search-console-shows-couldnt-fetch-or-sitemap-could-not-be-read) This is a well known Google Search Console issue where it reports "Couldn't fetch" or "Sitemap could not be read" even though the sitemap XML is perfectly valid. This is not caused by the module. **Why it happens:** Google caches sitemap fetch results. When you first submit a sitemap (or resubmit at the same URL), Google may return a stale cached failure instead of actually re-fetching the sitemap. This is especially common when: - You've just deployed your site for the first time - You've recently added the sitemap module - Google previously crawled the URL and found no sitemap **How to verify your sitemap is fine:** 1. Open the [URL Inspection tool](https://search.google.com/search-console?action=inspect) in Google Search Console 2. Paste your sitemap URL (e.g. `https://example.com/sitemap.xml`) 3. Click **Live test** 4. Expand the **Page availability** section and confirm: Crawl allowed = "Yes", Page fetch = "Successful", Indexing allowed = "Yes" If the live test passes, your sitemap is valid and the "Couldn't fetch" status is a Google caching issue. **Workarounds:** #### [Wait it out](#wait-it-out) In most cases the error resolves itself within 24 to 72 hours without any changes on your end. #### [Remove and resubmit in Search Console](#remove-and-resubmit-in-search-console) Remove your sitemap from the Google Search Console Sitemaps report, then resubmit it. Google will discover any sub-sitemaps (e.g. locale-specific sitemaps) automatically from the sitemap index. #### [Change the sitemap URL to force a fresh fetch](#change-the-sitemap-url-to-force-a-fresh-fetch) Google caches results by URL. Changing the sitemap filename forces Google to treat it as a new sitemap, bypassing any cached failures. You can do this with the `sitemapName` option: nuxt.config.ts ``` export default defineNuxtConfig({ sitemap: { sitemapName: 'sitemap_index.xml', }, }) ``` After deploying, submit the new URL in Google Search Console. This workaround has consistently resolved the issue immediately for affected users. You can validate your sitemap independently using the [XML Sitemap Validator](https://nuxtseo.com/tools/xml-sitemap-validator) or [xml-sitemaps.com](https://www.xml-sitemaps.com/validate-xml-sitemap.html) to confirm the issue is on Google's side. ### [Getting 404/Error when Pinging Google?](#getting-404error-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?](#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](https://nuxtseo.com/docs/sitemap/guides/dynamic-urls#handling-pre-encoded-urls) for more details. ## [Debugging Tools](#debugging-tools) - [XML Sitemap Validator](https://nuxtseo.com/tools/xml-sitemap-validator) - Validate sitemap structure, check URL format, and test against Google requirements [Edit this page](https://github.com/nuxt-modules/sitemap/edit/main/docs/content/0.getting-started/3.troubleshooting.md) [Markdown For LLMs](https://nuxtseo.com/docs/sitemap/getting-started/troubleshooting.md) Did this page help you? ### Related [Customising the UI](https://nuxtseo.com/docs/sitemap/advanced/customising-ui) [Submitting Your Sitemap](https://nuxtseo.com/docs/sitemap/guides/submitting-sitemap) [Nuxt SEO Troubleshooting](https://nuxtseo.com/docs/nuxt-seo/getting-started/troubleshooting) [Data Sources Understand where your sitemap URLs come from.](https://nuxtseo.com/docs/sitemap/getting-started/data-sources) [Dynamic URL Endpoints Use runtime API endpoints to generate dynamic URLs for your sitemap.](https://nuxtseo.com/docs/sitemap/guides/dynamic-urls) On this page - [Debugging](#debugging) - [Submitting an Issue](#submitting-an-issue) - [Troubleshooting FAQ](#troubleshooting-faq) - [Debugging Tools](#debugging-tools) [GitHub](https://github.com/harlan-zw/nuxt-seo) [ Discord](https://discord.com/invite/275MBUBvgP) ### [NuxtSEO](https://nuxtseo.com/ "Home") - [Getting Started](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction) - [MCP](https://nuxtseo.com/docs/nuxt-seo/guides/mcp) Modules - [Robots](https://nuxtseo.com/docs/robots/getting-started/introduction) - [Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction) - [OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction) - [Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction) - [Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction) - [SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction) - [Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction) - [Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction) - [AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction) ### [NuxtSEO Pro](https://nuxtseo.com/pro "Nuxt SEO Pro") - [Getting Started](https://nuxtseo.com/pro) - [Dashboard](https://nuxtseo.com/pro/dashboard) - [Pro MCP](https://nuxtseo.com/pro/docs/getting-started/mcp-setup) ### [Learn SEO](https://nuxtseo.com/learn-seo "Learn SEO") Nuxt - [Mastering Meta](https://nuxtseo.com/learn-seo/nuxt/mastering-meta) - [Controlling Crawlers](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers) - [Launch & Listen](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen) - [Routes & Rendering](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering) - [Staying Secure](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/security) Vue - [Vue SEO Guide](https://nuxtseo.com/learn-seo/vue) - [Mastering Meta](https://nuxtseo.com/learn-seo/vue/mastering-meta) - [Controlling Crawlers](https://nuxtseo.com/learn-seo/vue/controlling-crawlers) - [SPA SEO](https://nuxtseo.com/learn-seo/vue/spa) - [SSR Frameworks](https://nuxtseo.com/learn-seo/vue/ssr-frameworks) - [SEO Checklist](https://nuxtseo.com/learn-seo/checklist) - [Pre-Launch Warmup](https://nuxtseo.com/learn-seo/pre-launch-warmup) - [Backlinks & Authority](https://nuxtseo.com/learn-seo/backlinks) ### [Tools](https://nuxtseo.com/tools "SEO Tools") - [Social Share Debugger](https://nuxtseo.com/tools/social-share-debugger) - [Robots.txt Generator](https://nuxtseo.com/tools/robots-txt-generator) - [Meta Tag Checker](https://nuxtseo.com/tools/meta-tag-checker) - [HTML to Markdown](https://nuxtseo.com/tools/html-to-markdown) - [XML Sitemap Validator](https://nuxtseo.com/tools/xml-sitemap-validator) - [Schema.org Validator](https://nuxtseo.com/tools/schema-validator) - [Keyword Idea Generator](https://nuxtseo.com/tools/keyword-generator) - [Keyword Research](https://nuxtseo.com/tools/keyword-research) - [SERP Analyzer](https://nuxtseo.com/tools/serp-analyzer) - [Domain Rankings](https://nuxtseo.com/tools/domain-rankings) Copyright © 2023-2026 Harlan Wilton - [MIT License](https://github.com/harlan-zw/nuxt-seo/blob/main/license) · [mdream](https://mdream.dev)