facebook/docusaurus · error · Error

The versions file should contain an array of version names!

Error message

The versions file should contain an array of version names! Found content: ${JSON.stringify(names)}

What it means

Thrown by validateVersionNames() before iterating entries. The function expects versions.json to deserialize to a JSON array; if the top-level value is anything else (an object, a string, a number, null), the build fails with a JSON dump of the offending content. Each element of the (valid) array is then passed to validateVersionName.

Source

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

    // 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);
}

/**
 * @throws Throws for one of the following invalid options:
 * - `lastVersion` is non-existent
 * - `versions` includes unknown keys
 * - `onlyIncludeVersions` is empty, contains unknown names, or doesn't include
 * `latestVersion` (if provided)
 */
export function validateVersionsOptions(
  availableVersionNames: string[],

View on GitHub (pinned to 3f483e80e3)

Solutions

Rewrite versions.json as a JSON array of version-name strings, e.g. ["1.4", "1.3"].
If you need per-version config, that goes in docusaurus.config.js under docs.versions, NOT in versions.json.
Validate the file parses to Array.isArray(...) before committing.

Example fix

// versions.json - before (object)
{"1.4": {}, "1.3": {}}

// after (flat string array)
["1.4", "1.3"]

Defensive patterns

Strategy: type-guard

Validate before calling

const fs = require('fs');
function validateVersionsJsonIsArray(filePath) {
  const json = JSON.parse(fs.readFileSync(filePath, 'utf8'));
  if (!Array.isArray(json)) {
    throw new Error(`versions.json must be a JSON array of strings, got ${typeof json}`);
  }
}

Type guard

function isStringArray(value) {
  return Array.isArray(value) && value.every((v) => typeof v === 'string');
}

Prevention

Keep versions.json as a flat JSON array of strings only.
Put per-version config in docusaurus.config.js (docs.versions), not in versions.json.
Add a JSON-schema check in CI to enforce the array-of-strings shape.

When it happens

Trigger: versions.json is an object like {"1.4": {...}} instead of an array; the file contains a bare string or number at the top level; the file is null or corrupted JSON that parsed to a non-array; a tool wrote key/value pairs instead of a list.

Common situations: Hand-editing versions.json into a map; merging configs; copy-paste from a different format; corrupted write.

Related errors

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