facebook/docusaurus · error · Error

Invalid version name "${name}": version name ${message}.

Error message

Invalid version name "${name}": version name ${message}.

What it means

Thrown by validateVersionName() during the regex rule loop. After type and non-empty checks, the name is tested against four patterns: forward/backslash (/ \), length >= 33 chars, characters invalid in file paths (< > : " | ? * and control chars 0x00-0x1F), and the literal names '.' or '..'. If any matches, the build fails naming which rule was violated. Version names become directory names under versioned_docs/, so they must be path-safe.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/versions/validation.ts:34

      )}.`,
    );
  }
  if (!name.trim()) {
    throw new Error(
      `Invalid version name "${name}": version name must contain at least one non-whitespace character.`,
    );
  }
  const errors: [RegExp, string][] = [
    [/[/\\]/, 'should not include slash (/) or backslash (\\)'],
    [/.{33,}/, 'cannot be longer than 32 characters'],
    // eslint-disable-next-line no-control-regex
    [/[<>:"|?*\x00-\x1F]/, 'should be a valid file path'],
    [/^\.\.?$/, 'should not be "." or ".."'],
  ];

  errors.forEach(([pattern, message]) => {
    if (pattern.test(name)) {
      throw new Error(
        `Invalid version name "${name}": version name ${message}.`,
      );
    }
  });
}

export function validateVersionNames(
  names: unknown,
): asserts names is string[] {
  if (!Array.isArray(names)) {
    throw new Error(
      `The versions file should contain an array of version names! Found content: ${JSON.stringify(
        names,
      )}`,
    );
  }

  names.forEach(validateVersionName);

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Use a short, simple, path-safe version string like '1.4' or '1.4.0-beta'.
2. Remove any slash, backslash, or the characters <>:"|?*.
3. Trim the name to 32 characters or fewer.
4. Avoid '.' and '..' as version names.

Example fix

// versions.json - before
["1.4/beta", "release-2024-01-01-super-long-pre-release-label"]

// after: path-safe, short
["1.4-beta", "2024-01-01"]

const RULES = [
  {re: /[/\\]/, msg: 'no slash or backslash'},
  {re: /.{33,}/, msg: 'max 32 chars'},
  {re: /[<>:"|?*\x00-\x1F]/, msg: 'no invalid path chars'},
  {re: /^\.\.?$/, msg: 'not . or ..'},
];
function validateVersionNameRules(name) {
  for (const {re, msg} of RULES) {
    if (re.test(name)) throw new Error(`Version name '${name}' invalid: ${msg}`);
  }
}

function isPathSafeVersionName(name) {
  return typeof name === 'string' &&
    name.trim().length > 0 &&
    name.length <= 32 &&
    !/[/\\<>:"|?*\x00-\x1F]/.test(name) &&
    name !== '.' && name !== '..';
}

When it happens

Trigger: A version name with a slash like '1.4/beta'; a name longer than 32 characters; a name containing characters illegal on Windows (<>:"|?*); a name that is exactly '.' or '..'; control characters pasted from a clipboard.

Common situations: Using semantic version ranges as names ('>=1.4'); very long pre-release labels; cross-platform path issues from special chars; accidental '.' or '..' from relative path confusion.

Related errors

• The docs folder does not exist for version "${versionName}".
• Docs version "${versionMetadata.versionName}" has no docs! A
• Versions should be strings. Found type "${typeof name}" for
• Invalid version name "${name}": version name must contain at
• The versions file should contain an array of version names!

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