facebook/docusaurus · error · Error

Invalid sidebar items collection code=${JSON.stringify(sideb

Error message

Invalid sidebar items collection code=${JSON.stringify(sidebar)} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.

What it means

Thrown by normalizeSidebar() while the docs plugin converts the user's sidebars.js into its normalized internal form. A sidebar (or a category's items field, or an items slice) must be either an array of sidebar items or a categories shorthand object (an object whose keys are labels and whose values are item arrays, and which does NOT carry a top-level type property). Anything else is rejected.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts:71

  if (item.type === 'category') {
    const normalizedCategory: NormalizedSidebarItemCategory = {
      ...item,
      items: normalizeSidebar(
        item.items,
        logger.interpolate`code=${'items'} of the category name=${item.label}`,
      ),
    };
    return [normalizedCategory];
  }
  return [item];
}

function normalizeSidebar(
  sidebar: SidebarConfig,
  place: string,
): NormalizedSidebar {
  if (!Array.isArray(sidebar) && !isCategoriesShorthand(sidebar)) {
    throw new Error(
      logger.interpolate`Invalid sidebar items collection code=${JSON.stringify(
        sidebar,
      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
    );
  }

  const normalizedSidebar = Array.isArray(sidebar)
    ? sidebar
    : normalizeCategoriesShorthand(sidebar);

  return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem));
}

export function normalizeSidebars(
  sidebars: SidebarsConfig,
): NormalizedSidebars {
  return _.mapValues(sidebars, (sidebar, id) =>
    normalizeSidebar(sidebar, logger.interpolate`sidebar name=${id}`),

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Wrap the offending value in an array: change `mySidebar: {type:'category',...}` to `mySidebar: [{type:'category',...}]`.
2. If you meant shorthand notation, remove any top-level type key from the object so it is read as label->items pairs.
3. Inspect the place token in the message (it names the sidebar / category / items slice) to locate the exact malformed node, then fix that node's shape.
4. Validate the sidebars export against the documented shapes at https://docusaurus.io/docs/sidebar/items before rebuilding.

Example fix

// before: object with type where array expected
const sidebars = {
  tutorial: {type: 'category', label: 'Tutorial', items: ['intro']},
};

// after: array of items
const sidebars = {
  tutorial: [{type: 'category', label: 'Tutorial', items: ['intro']}],
};

const {isCategoriesShorthand} = require('@docusaurus/plugin-content-docs/lib/sidebars/utils');
function isValidSidebarRoot(node) {
  return Array.isArray(node) || isCategoriesShorthand(node);
}
// Throw with a helpful message before the build does.
Object.entries(sidebars).forEach(([name, node]) => {
  if (!isValidSidebarRoot(node)) {
    throw new Error(`Sidebar '${name}' must be an array or a categories shorthand object.`);
  }
});

function isCategoriesShorthand(node) {
  return (
    typeof node === 'object' &&
    node !== null &&
    !Array.isArray(node) &&
    !('type' in node)
  );
}
function isValidSidebar(node) {
  return Array.isArray(node) || isCategoriesShorthand(node);
}

When it happens

Trigger: Returning a single sidebar item object from a function instead of wrapping it in an array; putting an object with a type property where the shorthand notation is expected; nesting a category's items as an object with type instead of an array; exporting a sidebar whose root is a bare string or a number.

Common situations: Refactoring sidebars.js and forgetting to wrap an item in []; copying a single category object from the docs into a sidebar key; accidentally assigning a full SidebarItemConfig (with type:'category') to a top-level sidebar entry that the parser tries to read as shorthand; JSON sidebars where a category's items field was serialized as an object map.

Related errors

• Invalid sidebar file at "${toMessageRelativeFilePath(sidebar
• Invalid sidebars file. The document with id "${docId}" was u
• Can't find any doc with ID ${docId}. Available doc IDs: - ${
• Sidebar category ${item.label} has neither any subitem nor a
• Multiple docs sidebar items produce the same translation key

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