facebook/docusaurus · error · Error

Invalid docs option "onlyIncludeVersions": an empty array is

Error message

Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.

What it means

Thrown by validateVersionsOptions when docs.onlyIncludeVersions is provided as an array but is empty. onlyIncludeVersions filters which versions are built; an empty filter would build nothing, so the plugin rejects it to fail fast. At least one version name is required.

Source

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

    throw new Error(
      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
    );
  }
  const unknownVersionConfigNames = _.difference(
    Object.keys(options.versions),
    availableVersionNames,
  );
  if (unknownVersionConfigNames.length > 0) {
    throw new Error(
      `Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(
        ',',
      )}) found. ${availableVersionNamesMsg}`,
    );
  }

  if (options.onlyIncludeVersions) {
    if (options.onlyIncludeVersions.length === 0) {
      throw new Error(
        `Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`,
      );
    }
    const unknownOnlyIncludeVersionNames = _.difference(
      options.onlyIncludeVersions,
      availableVersionNames,
    );
    if (unknownOnlyIncludeVersionNames.length > 0) {
      throw new Error(
        `Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(
          ',',
        )}) found. ${availableVersionNamesMsg}`,
      );
    }
    if (
      options.lastVersion &&
      !options.onlyIncludeVersions.includes(options.lastVersion)
    ) {

View on GitHub (pinned to 3f483e80e3)

Solutions

Populate onlyIncludeVersions with at least one valid version name from the available list.
If you want all versions, omit onlyIncludeVersions entirely instead of passing [].
Guard dynamic arrays: only set it when length > 0.

Example fix

// before
docs: { onlyIncludeVersions: [] }
// after
docs: { onlyIncludeVersions: ['current', '1.0'] }
// or simply omit it
docs: {}

Defensive patterns

Strategy: validation

Validate before calling

if (Array.isArray(config.onlyIncludeVersions) && config.onlyIncludeVersions.length === 0) {
  throw new Error('onlyIncludeVersions must not be empty');
}

Type guard

const isNonEmptyStringArray = (v: unknown): v is string[] =>
  Array.isArray(v) && v.length > 0 && v.every(x => typeof x === 'string');

Prevention

When computing onlyIncludeVersions dynamically, fall back to undefined (all versions) when the list is empty.
Unit-test config generators for the empty-list edge case.

When it happens

Trigger: Setting onlyIncludeVersions: [] in docs options, or programmatically building the array from a filter that yields no values.

Common situations: Dynamically computing onlyIncludeVersions (e.g. from an env var or CI matrix) and the source list being empty; refactoring that leaves a placeholder empty array; misconfigured partial builds.

Related errors

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