facebook/docusaurus · error · Error

Invalid name=${plugin} version number=${versionInfo.version}

Error message

Invalid name=${plugin} version number=${versionInfo.version}.\nAll official @docusaurus/* packages should have the exact same version as @docusaurus/core (number=${docusaurusVersion}).\nMaybe you want to check, or regenerate your yarn.lock or package-lock.json file?

What it means

Thrown by `checkDocusaurusPackagesVersion` when any loaded official `@docusaurus/*` plugin has a version different from `@docusaurus/core`. Docusaurus requires all first-party packages to share one version to avoid runtime incompatibilities. The message tells you which plugin mismatched and suggests regenerating the lockfile.

Source

Thrown at packages/docusaurus/src/server/siteMetadata.ts:94

  return {type: 'local'};
}

/**
 * We want all `@docusaurus/*` packages to have the exact same version!
 * @see https://github.com/facebook/docusaurus/issues/3371
 * @see https://github.com/facebook/docusaurus/pull/3386
 */
function checkDocusaurusPackagesVersion(siteMetadata: SiteMetadata) {
  const {docusaurusVersion} = siteMetadata;
  Object.entries(siteMetadata.pluginVersions).forEach(
    ([plugin, versionInfo]) => {
      if (
        versionInfo.type === 'package' &&
        versionInfo.name?.startsWith('@docusaurus/') &&
        versionInfo.version &&
        versionInfo.version !== docusaurusVersion
      ) {
        throw new Error(`Invalid name=${plugin} version number=${versionInfo.version}.
All official @docusaurus/* packages should have the exact same version as @docusaurus/core (number=${docusaurusVersion}).
Maybe you want to check, or regenerate your yarn.lock or package-lock.json file?`);
      }
    },
  );
}

export function createSiteMetadata({
  siteVersion,
  plugins,
}: {
  siteVersion: string | undefined;
  plugins: LoadedPlugin[];
}): SiteMetadata {
  const siteMetadata: SiteMetadata = {
    docusaurusVersion: DOCUSAURUS_VERSION,
    siteVersion,
    pluginVersions: Object.fromEntries(

View on GitHub (pinned to 3f483e80e3)

Solutions

Align all `@docusaurus/*` deps to a single version in package.json.
Regenerate the lockfile: `rm -rf node_modules package-lock.json && npm install` (or `pnpm install`).
Use `npm ls @docusaurus/core` / `pnpm why @docusaurus/plugin-content-docs` to find the divergent copy.
Re-run `create-docusaurus` upgrade or the versioned upgrade guide for your target release.

Example fix

// before (package.json)
"@docusaurus/core": "3.4.0",
"@docusaurus/plugin-content-docs": "3.1.0",
// after
"@docusaurus/core": "3.4.0",
"@docusaurus/plugin-content-docs": "3.4.0",

Defensive patterns

Strategy: validation

Validate before calling

const docusaurusPkgs = Object.keys(require('./package.json').dependencies)
  .filter(k => k.startsWith('@docusaurus/'));
const versions = new Set(docusaurusPkgs.map(name => require(`${name}/package.json`).version));
if (versions.size !== 1) throw new Error('Mixed @docusaurus/* versions detected');

Prevention

Use a single version range for all `@docusaurus/*` deps (e.g. all `^3.4.0`).
Regenerate the lockfile after every Docusaurus upgrade.
Run `npm ls @docusaurus/core` in CI to detect version drift.

When it happens

Trigger: Mixing versions in node_modules — e.g. `@docusaurus/core@3.4` with `@docusaurus/plugin-content-docs@3.1`. The loop at siteMetadata.ts:88-103 checks each `pluginVersions` entry whose name starts with `@docusaurus/` and throws on mismatch.

Common situations: Partial upgrades (upgrading core but not plugins); stale lockfile after a version bump; npm/pnpm hoisting differences across a monorepo; conflicting peer resolutions from third-party presets.

Related errors

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