Generated sitemap is not escaped and is invalid if a URL has the character `&`

[joulev]

Link to the code that reproduces this issue

https://github.com/joulev/debug/tree/nextjs-sitemap-escape-ampersand

To Reproduce

// app/sitemap.ts
import type { MetadataRoute } from 'next';

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
    return [
        {
            url: 'https://example.com?a=b&c=d',
            changeFrequency: 'never',
        },      
    ]
}

Current vs. Expected behavior

Current: The & is not escaped, causing the sitemap file to be invalid.

Expected: The URL should be properly escaped. Right now a workaround is required with .replaceAll('&', '&'). But, if this issue is fixed, it will break this workaround, so not even sure if that fix should belong to a new major or not.

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
  Version: #25~22.04.1-Ubuntu SMP Thu Jan 16 21:37:09 UTC 2025
  Available memory (MB): 7939
  Available CPU cores: 2
Binaries:
  Node: 18.20.7
  npm: 10.8.2
  Yarn: 1.22.22
  pnpm: 10.6.4
Relevant Packages:
  next: 15.3.0-canary.15 // Latest available version is detected (15.3.0-canary.15).
  eslint-config-next: N/A
  react: 19.0.0
  react-dom: 19.0.0
  typescript: 5.8.2
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Metadata

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local), next start (local), Vercel (Deployed), Other (Deployed)

Additional context

No response

[Austin1serb]

Hey @joulev, I've reproduced this issue and confirmed your findings—URLs containing special characters like & are not properly escaped, causing invalid XML sitemaps.

🔍 Root Cause:

Next.js currently doesn't escape special XML characters (&, <, >, ", ') when generating sitemaps via the Metadata API, resulting in invalid sitemap files.

😅 Problem with Fixing This Directly:

If Next.js blindly escapes all URLs, it could break existing workarounds where users have already manually escaped & to &.

For example:

// Current workaround in user code
url: "https://example.com?a=b&c=d",

If Next.js automatically escapes this, it would double-escape &, resulting in something like:

https://example.com?a=b&c=d

which is incorrect.

✅ Recommended High Level Solution:

A better approach is to only escape when necessary. Here’s a high level approach to how Next.js could handle this:

function escapeXml(url: string): string {
  // Avoid double escaping: Only escape if `&` is not already part of `&`, `<`, etc.
  if (/&(amp|lt|gt|quot|apos);/.test(url)) {
    return url; // Assume already escaped
  }

  return url.replace(/[<>&'\"]+/g, (char) => {
    switch (char) {
      case '&': return '&amp;';
      case '<': return '&lt;';
      case '>': return '&gt;';
      case '"': return '&quot;';
      case "'": return '&apos;';
      default: return char;
    }
  });
}

🚀 Next Steps:

Would love feedback from the maintainers! I’m happy to dive deeper into this problem, consider every edge case, and submit a PR.

[joulev]

Uh... thanks??

[Austin1serb]

Just submitted a PR to fix this: #77054 — escaping XML characters in sitemap <loc> URLs to prevent invalid XML.

While working through it, I also noticed other parts of the sitemap — like alternates.languages[lang] and images or videos — can also contain user-defined URLs. If those include characters like &, they could potentially break the XML too.

Might be worth reviewing whether we should apply the same escape logic in those spots as well (or at least document expectations for those fields).

Happy to explore that further if helpful!