facebook/docusaurus · error

Can't generate a sitemap with no items

Error message

Can't generate a sitemap with no items

What it means

Thrown by sitemapItemsToXmlString when called with an empty items array. Although an empty sitemap is technically valid XML, the underlying 'sitemap' library has a bug that would leave the stream unresolved, so Docusaurus fails fast instead of hanging. This is a guard inside the sitemap plugin's XML generation.

Source

Thrown at packages/docusaurus-plugin-sitemap/src/xml.ts:18

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

import {SitemapStream, streamToPromise} from 'sitemap';
import type {LastModOption, SitemapItem} from './types';

export async function sitemapItemsToXmlString(
  items: SitemapItem[],
  options: {lastmod: LastModOption | null},
): Promise<string> {
  if (items.length === 0) {
    // Note: technically we could, but there is a bug in the lib code
    // and the code below would never resolve, so it's better to fail fast
    throw new Error("Can't generate a sitemap with no items");
  }

  // TODO remove sitemap lib dependency?
  //  https://github.com/ekalinin/sitemap.js
  //  it looks like an outdated confusion super old lib
  //  we might as well achieve the same result with a pure xml lib
  const sitemapStream = new SitemapStream({
    // WTF is this lib reformatting the string YYYY-MM-DD to datetime...
    lastmodDateOnly: options?.lastmod === 'date',
  });

  items.forEach((item) => sitemapStream.write(item));
  sitemapStream.end();

  const buffer = await streamToPromise(sitemapStream);
  return buffer.toString();
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Ensure at least one crawlable route exists (a published page/doc/post that isn't noindex/unlisted).
2. Check that you didn't exclude the whole site via sitemap filter or head tags.
3. If genuinely empty sitemaps are expected, disable the sitemap plugin rather than feeding it zero items.

if (items.length === 0) {
  // skip sitemap generation instead of calling sitemapItemsToXmlString
  return;
}

const hasItems = (items: unknown[]): boolean => items.length > 0;

When it happens

Trigger: The plugin computed zero URLs to emit (every route excluded, no docs/blog/pages routes, or all pages marked noindex/unlisted) and then attempted to render the sitemap.

Common situations: A site where the sitemap plugin runs but all routes are filtered out; misconfigured excludePatterns/hreflang; a dev/build environment with no content; integrating sitemap with a custom route provider that returns nothing.

Related errors

• HTML minification failed (Terser)
• HTML minification failed (SWC)
• MDX compilation failed for file ${logger.path(filePath)} Cau
• Some created redirects are invalid: - ${redirectValidationEr
• You are trying to create client-side redirections to invalid

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/c8d22cb60f4192a5. Report an issue: GitHub.