facebook/docusaurus · error · Error

Invalid version name "${name}": version name must contain at

Error message

Invalid version name "${name}": version name must contain at least one non-whitespace character.

What it means

Thrown by validateVersionName() after the type check passes. If the (string) name trims to an empty string, the build fails because a version name must contain at least one non-whitespace character. This is the second of three sequential checks.

Source

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

 * 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 _ from 'lodash';
import type {VersionsOptions} from '@docusaurus/plugin-content-docs';

export function validateVersionName(name: unknown): asserts name is string {
  if (typeof name !== 'string') {
    throw new Error(
      `Versions should be strings. Found type "${typeof name}" for version ${JSON.stringify(
        name,
      )}.`,
    );
  }
  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}.`,
      );
    }
  });

View on GitHub (pinned to 3f483e80e3)

Solutions

Remove the empty/whitespace entry from versions.json.
Replace it with a real version name like "1.4".
Sanitize generated versions.json by filtering out names that do not trim to a non-empty string.

Example fix

// versions.json - before
["1.4", "   ", "1.3"]

// after
["1.4", "1.3"]

Defensive patterns

Strategy: validation

Validate before calling

function rejectBlankVersionNames(names) {
  names.forEach((name, i) => {
    if (typeof name === 'string' && !name.trim()) {
      throw new Error(`versions.json[${i}] is blank/whitespace-only`);
    }
  });
}

Type guard

function isNonBlankString(name) {
  return typeof name === 'string' && name.trim().length > 0;
}

Prevention

Filter out empty strings when generating versions.json: names.filter((n) => n.trim()).
Avoid trailing commas in hand-edited JSON.
Validate the file before committing.

When it happens

Trigger: versions.json contains "" or " " (spaces/tabs only) as a version entry; a trailing comma produced an empty element; copy-paste left a blank slot; programmatic generation wrote an empty string placeholder.

Common situations: Editing versions.json and leaving a stray empty entry; templating that emits blank values; whitespace-only values from misformatted YAML/JSON.

Related errors

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