facebook/docusaurus · error · Error

unknown item type ${JSON.stringify(item)}

Error message

unknown item type ${JSON.stringify(item)}

What it means

Thrown by `DocCard` when `item.type` is neither `'link'` nor `'category'`. `DocCard` renders sidebar items in a docs sidebar grid, and the sidebar item taxonomy is restricted to those two kinds. Hitting `default` means the docs sidebar data contains an item type the renderer does not know how to draw.

Source

Thrown at packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx:85

  return (
    <Layout
      item={item}
      className={item.className}
      href={item.href}
      description={item.description ?? doc?.description}
      {...getIconTitleProps(item)}
    />
  );
}

export default function DocCard({item}: Props): ReactNode {
  switch (item.type) {
    case 'link':
      return <CardLink item={item} />;
    case 'category':
      return <CardCategory item={item} />;
    default:
      throw new Error(`unknown item type ${JSON.stringify(item)}`);
  }
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Check the `type` field of every item returned by your `sidebarItemsGenerator`; only `'link'` and `'category'` are renderable by `DocCard`.
2. If you need other types, render them with a custom/swizzled `DocCard` that handles them before the `default` branch.
3. Validate the sidebar tree shape against the `SidebarsDoc`/sidebar item types from `@docusaurus/plugin-content-docs`.

Example fix

// before (custom generator returns wrong type)
async function myGenerator({isCategoryIndex}) {
  return [{type: 'doc', id: 'intro', label: 'Intro'}]; // 'doc' is invalid for DocCard
}
// after
async function myGenerator() {
  return [{type: 'link', href: '/docs/intro', label: 'Intro'}];
}

function isDocCardItem(item: {type?: string}): boolean {
  return item.type === 'link' || item.type === 'category';
}
// in a custom sidebarItemsGenerator, filter/validate before returning

import type {SidebarsDoc} from '@docusaurus/plugin-content-docs';
type DocCardItem = Extract<SidebarsDoc, {type:'link'}> | Extract<SidebarsDoc,{type:'category'}>;
function isDocCardItem(item: any): item is DocCardItem {
  return item?.type === 'link' || item?.type === 'category';
}

When it happens

Trigger: A custom sidebar generator (the `async sidebarItems` callback in `docusaurus.config`) returns an object whose `type` is something other than `'link'` or `'category'`. Also possible if a swizzled `DocCard` was not updated after a new sidebar item type was introduced elsewhere.

Common situations: Authoring a custom `sidebarItemsGenerator` that emits items with `type: 'doc'` or `type: 'html'` (those are navbar/sidebar-item kinds, not DocCard kinds); mismatched swizzle after an upgrade; feeding hand-built sidebar JSON with a wrong `type` field.

Related errors

• unexpected color mode ${colorMode}
• Wrong icon: ${icon}
• DocSidebarNavbarItem: Sidebar with ID "${sidebarId}" doesn't
• Docusaurus plugin global data not found for "${pluginName}"
• Docusaurus plugin global data not found for "${pluginName}"

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