facebook/docusaurus · error · Error

We couldn't compute a valid slug for document with ID "${bas

Error message

We couldn't compute a valid slug for document with ID "${baseID}" in "${sourceDirName}" directory.
The slug we computed looks invalid: ${slug}.
Maybe your slug front matter is incorrect or there are special characters in the file path?
By using front matter to set a custom slug, you should be able to fix this error:

---
slug: /my/customDocPath
---

What it means

Thrown by ensureValidSlug() inside getSlug(). After computing a doc's slug (from front matter slug, the directory name slug, or the base id resolved against the dir slug), Docusaurus validates it with isValidPathname(). If the result is not a valid URL pathname (e.g. contains spaces, illegal chars, is empty, or does not start with a slash after resolution), the build fails and the message suggests setting an explicit slug.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/slug.ts:63

  function computeSlug(): string {
    if (frontMatterSlug?.startsWith('/')) {
      return frontMatterSlug;
    }
    const dirNameSlug = getDirNameSlug();
    if (
      !frontMatterSlug &&
      isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName}))
    ) {
      return dirNameSlug;
    }
    const baseSlug = frontMatterSlug ?? baseID;
    return resolvePathname(baseSlug, getDirNameSlug());
  }

  function ensureValidSlug(slug: string): string {
    if (!isValidPathname(slug)) {
      throw new Error(
        `We couldn't compute a valid slug for document with ID "${baseID}" in "${sourceDirName}" directory.
The slug we computed looks invalid: ${slug}.
Maybe your slug front matter is incorrect or there are special characters in the file path?
By using front matter to set a custom slug, you should be able to fix this error:

---
slug: /my/customDocPath
---
`,
      );
    }
    return slug;
  }

  return ensureValidSlug(computeSlug());
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Set an explicit slug in the doc's front matter, starting with a leading slash and using only URL-safe path segments.
2. Rename the source file or directory to remove spaces and special characters so the auto-computed slug is valid.
3. If using slug_base in _category_.json, ensure each segment is a clean URL path.
4. Confirm the slug is not empty after trimming and that resolvePathname produces a value starting with '/'.

Example fix

---
# before
id: mydoc
slug: my doc
---

---
# after: leading slash, URL-safe
id: mydoc
slug: /my/customDocPath
---

const {isValidPathname} = require('@docusaurus/utils');
// Validate a slug before the build does.
function validateSlug(slug) {
  if (!isValidPathname(slug)) {
    throw new Error(`Slug '${slug}' is not a valid pathname; use a leading slash and URL-safe segments.`);
  }
  return slug;
}

function isValidSlug(slug) {
  return typeof slug === 'string' && slug.startsWith('/') && !/\s/.test(slug) && isValidPathname(slug);
}

When it happens

Trigger: A slug front matter value like `slug: my doc` (no leading slash, contains a space); a doc whose computed base id contains characters that resolvePathname cannot normalize; a category-index slug derived from a directory name with special characters; resolving a relative slug against a root-level dir produces an invalid pathname.

Common situations: Non-ASCII or emoji in filenames; Windows-incompatible characters in paths; front matter slug authored without a leading slash; very long or whitespace-heavy directory names; slug_base conflicts producing empty segments.

Related errors

• Document id "${baseID}" cannot include slash.
• Error when loading ${doc.id} in ${doc.sourceDirName}: the pa
• Can't find any doc with ID ${docId}. Available doc IDs: - ${
• Invalid sidebar items collection code=${JSON.stringify(sideb
• Sidebar category ${item.label} has neither any subitem nor a

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