facebook/docusaurus · error · Error

Docusaurus error: The <Tabs> has a defaultValue "${defaultVa

Error message

Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${tabValues.map((a) => a.value).join(', ')}. If you intend to show no default tab, use defaultValue={null} instead.

What it means

The <Tabs> component validates that its defaultValue prop matches the value of one of its <TabItem> children (or entries in the values prop). This check runs inside getInitialStateValue at initial state computation; when defaultValue is truthy but no tab has that value, Docusaurus throws rather than silently render a non-existent tab. Use defaultValue={null} if you intentionally want no preselected tab.

Source

Thrown at packages/docusaurus-theme-common/src/utils/tabsUtils.tsx:144

  return tabValues.some((a) => a.value === value);
}

function getInitialStateValue({
  defaultValue,
  tabValues,
}: {
  defaultValue: TabsProps['defaultValue'];
  tabValues: readonly TabValue[];
}): string {
  if (tabValues.length === 0) {
    throw new Error(
      'Docusaurus error: the <Tabs> component requires at least one <TabItem> children component',
    );
  }
  if (defaultValue) {
    // Warn user about passing incorrect defaultValue as prop.
    if (!isValidValue({value: defaultValue, tabValues})) {
      throw new Error(
        `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${tabValues
          .map((a) => a.value)
          .join(
            ', ',
          )}. If you intend to show no default tab, use defaultValue={null} instead.`,
      );
    }
    return defaultValue;
  }
  const defaultTabValue =
    tabValues.find((tabValue) => tabValue.default) ?? tabValues[0];
  if (!defaultTabValue) {
    throw new Error('Unexpected error: 0 tabValues');
  }
  return defaultTabValue.value;
}

function getStorageKey(groupId: string | undefined) {

View on GitHub (pinned to 3f483e80e3)

Solutions

Set defaultValue to a value that exists on a <TabItem> (or in the values array). The error message lists all valid values.
Remove the defaultValue prop entirely to fall back to the first tab, or the one whose <TabItem default> is set.
Pass defaultValue={null} if you intentionally want no tab preselected.

Example fix

// before
<Tabs defaultValue="apple">
  <TabItem value="app">App</TabItem>
  <TabItem value="orange">Orange</TabItem>
</Tabs>
// after
<Tabs defaultValue="app">
  <TabItem value="app">App</TabItem>
  <TabItem value="orange">Orange</TabItem>
</Tabs>

Defensive patterns

Strategy: validation

Validate before calling

import type {TabsProps} from '@docusaurus/theme-common/internal';

function assertDefaultValueValid(
  defaultValue: TabsProps['defaultValue'],
  tabValues: readonly {value: string}[],
) {
  if (
    defaultValue &&
    !tabValues.some((t) => t.value === defaultValue)
  ) {
    throw new Error(
      `defaultValue '${defaultValue}' is not one of [${tabValues
        .map((t) => t.value)
        .join(', ')}]`,
    );
  }
}

Type guard

const isKnownTabValue = (
  v: string | null | undefined,
  tabValues: readonly {value: string}[],
): v is string =>
  v != null && tabValues.some((t) => t.value === v);

Prevention

Keep defaultValue in the same edit unit as the TabItem values so renames update both.
When generating values dynamically, derive defaultValue from tabValues[0].value instead of a literal.
Lint MDX for defaultValue props that do not appear in any value prop.

When it happens

Trigger: Render <Tabs defaultValue="apple"> whose <TabItem> children only have value="app"; pass a values={[{value:'a'},{value:'b'}]} array with defaultValue="c"; or hardcode a defaultValue after renaming a tab value.

Common situations: Renaming a TabItem value prop and forgetting to update defaultValue; copy-pasting a Tabs block and editing only some values; generating tab values dynamically while defaultValue stays hardcoded; refactoring MDX where defaultValue referenced a now-removed tab.

Related errors

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