facebook/docusaurus · error · Error

No docs version exist for name '${name}', please verify your

Error message

No docs version exist for name '${name}', please verify your 'docsVersionDropdown' navbar item versions config.
Available version names:
- ${versions.map((v) => `${v.name}`).join('\n- ')}

What it means

Thrown by `DocsVersionDropdownNavbarItem` when a version `name` listed under the navbar item's `versions` config does not match any of the versions Docusaurus actually knows about. The dropdown iterates the configured version names and looks each one up in the global version map; a miss is a config error.

Source

Thrown at packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx:52

};

function getVersionItems(
  versions: GlobalVersion[],
  configs?: PropVersions,
): VersionItem[] {
  if (configs) {
    // Collect all the versions we have
    const versionMap = new Map<string, GlobalVersion>(
      versions.map((version) => [version.name, version]),
    );

    const toVersionItem = (
      name: string,
      config?: PropVersionItem,
    ): VersionItem => {
      const version = versionMap.get(name);
      if (!version) {
        throw new Error(`No docs version exist for name '${name}', please verify your 'docsVersionDropdown' navbar item versions config.
Available version names:\n- ${versions.map((v) => `${v.name}`).join('\n- ')}`);
      }
      return {version, label: config?.label ?? version.label};
    };

    if (Array.isArray(configs)) {
      return configs.map((name) => toVersionItem(name, undefined));
    } else {
      return Object.entries(configs).map(([name, config]) =>
        toVersionItem(name, config),
      );
    }
  } else {
    return versions.map((version) => ({version, label: version.label}));
  }
}

function useVersionItems({

View on GitHub (pinned to 3f483e80e3)

Solutions

Read the error's 'Available version names' list and align your `versions` config to those exact strings.
Create the missing version with `docusaurus docs:version <name>` (or the `--plugin-id` variant) before referencing it.
Double-check `docsPluginId` matches the docs instance that owns those versions.
Remove stale version names left over from a docs prune.

Example fix

// before
navbar: [{
  type: 'docsVersionDropdown',
  versions: { '2.0': {label: 'v2'}, '9.9': {label: 'phantom'} } // 9.9 does not exist
}]
// after
navbar: [{
  type: 'docsVersionDropdown',
  versions: { '2.0': {label: 'v2'}, '1.0': {label: 'v1'} } // both exist
}]

Defensive patterns

Strategy: validation

Validate before calling

import {useVersions} from '@docusaurus/plugin-content-docs/client';
const versions = useVersions(pluginId);
const known = new Set(versions.map(v => v.name));
const cfgNames = Array.isArray(cfg) ? cfg : Object.keys(cfg);
const invalid = cfgNames.filter(n => !known.has(n));
if (invalid.length) { /* surface to user, do not pass to dropdown */ }

Type guard

function allVersionsExist(names: string[], known: string[]): boolean {
  const set = new Set(known);
  return names.every(n => set.has(n));
}

Prevention

Create a version with `docusaurus docs:version <name>` before listing it in `versions`.
Remove version names from `versions` when you delete a version.
Match `docsPluginId` to the owning docs instance.

When it happens

Trigger: The navbar item's `versions` array/object contains a version name (e.g. `'2.0'`) that is not present among the released/current versions for that docs plugin. The error message lists the actually-available names to help you correct the typo.

Common situations: Typo in a version name; referencing a version that was cut/removed; configuring `versions` before running `docusaurus docs:version <name>` to actually create it; mismatch between the `docsPluginId` on the navbar item and the instance whose versions you mean.

Related errors

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