{"record":{"id":"4d8c167c899604ae","repo":"facebook/docusaurus","slug":"we-couldn-t-compute-a-valid-slug-for-document-with","errorCode":null,"errorMessage":"We couldn't compute a valid slug for document with ID \"${baseID}\" in \"${sourceDirName}\" directory.\nThe slug we computed looks invalid: ${slug}.\nMaybe your slug front matter is incorrect or there are special characters in the file path?\nBy using front matter to set a custom slug, you should be able to fix this error:\n\n---\nslug: /my/customDocPath\n---\n","messagePattern":"We couldn't compute a valid slug for document with ID \"(.+?)\" in \"(.+?)\" directory\\.\nThe slug we computed looks invalid: (.+?)\\.\nMaybe your slug front matter is incorrect or there are special characters in the file path\\?\nBy using front matter to set a custom slug, you should be able to fix this error:\n\n---\nslug: /my/customDocPath\n---\n","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-content-docs/src/slug.ts","lineNumber":63,"sourceCode":"\n  function computeSlug(): string {\n    if (frontMatterSlug?.startsWith('/')) {\n      return frontMatterSlug;\n    }\n    const dirNameSlug = getDirNameSlug();\n    if (\n      !frontMatterSlug &&\n      isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName}))\n    ) {\n      return dirNameSlug;\n    }\n    const baseSlug = frontMatterSlug ?? baseID;\n    return resolvePathname(baseSlug, getDirNameSlug());\n  }\n\n  function ensureValidSlug(slug: string): string {\n    if (!isValidPathname(slug)) {\n      throw new Error(\n        `We couldn't compute a valid slug for document with ID \"${baseID}\" in \"${sourceDirName}\" directory.\nThe slug we computed looks invalid: ${slug}.\nMaybe your slug front matter is incorrect or there are special characters in the file path?\nBy using front matter to set a custom slug, you should be able to fix this error:\n\n---\nslug: /my/customDocPath\n---\n`,\n      );\n    }\n    return slug;\n  }\n\n  return ensureValidSlug(computeSlug());\n}\n","sourceCodeStart":45,"sourceCodeEnd":80,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/slug.ts#L45-L80","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set an explicit slug in the doc's front matter, starting with a leading slash and using only URL-safe path segments.","Rename the source file or directory to remove spaces and special characters so the auto-computed slug is valid.","If using slug_base in _category_.json, ensure each segment is a clean URL path.","Confirm the slug is not empty after trimming and that resolvePathname produces a value starting with '/'."],"exampleFix":"---\n# before\nid: mydoc\nslug: my doc\n---\n\n---\n# after: leading slash, URL-safe\nid: mydoc\nslug: /my/customDocPath\n---","handlingStrategy":"validation","validationCode":"const {isValidPathname} = require('@docusaurus/utils');\n// Validate a slug before the build does.\nfunction validateSlug(slug) {\n  if (!isValidPathname(slug)) {\n    throw new Error(`Slug '${slug}' is not a valid pathname; use a leading slash and URL-safe segments.`);\n  }\n  return slug;\n}","typeGuard":"function isValidSlug(slug) {\n  return typeof slug === 'string' && slug.startsWith('/') && !/\\s/.test(slug) && isValidPathname(slug);\n}","tryCatchPattern":null,"preventionTips":["Always author slug front matter with a leading slash and no spaces.","Keep filenames ASCII and free of special characters.","If a directory name is unfriendly, set slug_base in its _category_.json."],"tags":["docs","slug","frontmatter","configuration"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}