Unrecognized keys found in preset-classic configuration…

Error message

Unrecognized keys ${Object.keys(rest).join(', ')} found in preset-classic configuration. The allowed keys are debug, docs, blog, pages, sitemap, theme, googleAnalytics, gtag, and googleTagManager. Check the documentation: https://docusaurus.io/docs/using-plugins#docusauruspreset-classic for more information on how to configure individual plugins.

What it means

Thrown by preset-classic when, after destructuring the known option keys (debug, docs, blog, pages, sitemap, svgr, theme, gtag, googleTagManager, googleAnalytics), the rest object still has keys. Any unrecognized top-level preset option is rejected and the allowed set is printed along with a docs link. Note 'svgr' is accepted by code though not listed in the message text.

Solutions

Remove or rename the unrecognized keys listed in the message to match an allowed key.
If the option targets a specific plugin, pass it under the correct sub-key (e.g. docs, blog, pages).
If it's a theme option, move it to themeConfig instead of the preset.

Example fix

// before
presets: [['classic', { doc: { sidebarCollapsed: false } }]]
// after
presets: [['classic', { docs: { sidebarCollapsed: false } }]]

Defensive patterns

Strategy: validation

Validate before calling

const allowed = new Set(['debug','docs','blog','pages','sitemap','svgr','theme','gtag','googleTagManager','googleAnalytics']);
const unknown = Object.keys(presetOptions).filter(k => !allowed.has(k));
if (unknown.length) throw new Error(`Unknown preset keys: ${unknown.join(', ')}`);

Prevention

Type preset options against the published Options type to catch typos at compile time.
Keep theme-only settings in themeConfig, not on the preset.

When it happens

Trigger: Passing a misspelled or removed preset option, e.g. presets: [['classic', { doc: {...} }]] (typo), or a removed option like 'googleAnalytics' after the v4 guard, or any extra key not in the allowed list.

Common situations: Typos (doc/docs, teme/theme); options from outdated tutorials; options that belong on themeConfig placed on the preset; leftover keys after upgrades.

Related errors

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

Appendix: source

Thrown at packages/docusaurus-preset-classic/src/index.ts:108

  if (gtag) {
    plugins.push(makePluginConfig('@docusaurus/plugin-google-gtag', gtag));
  }
  if (googleTagManager) {
    plugins.push(
      makePluginConfig(
        '@docusaurus/plugin-google-tag-manager',
        googleTagManager,
      ),
    );
  }
  if (sitemap !== false && (isProd || debug)) {
    plugins.push(makePluginConfig('@docusaurus/plugin-sitemap', sitemap));
  }
  if (svgr !== false) {
    plugins.push(makePluginConfig('@docusaurus/plugin-svgr', svgr));
  }
  if (Object.keys(rest).length > 0) {
    throw new Error(
      `Unrecognized keys ${Object.keys(rest).join(
        ', ',
      )} found in preset-classic configuration. The allowed keys are debug, docs, blog, pages, sitemap, theme, googleAnalytics, gtag, and googleTagManager. Check the documentation: https://docusaurus.io/docs/using-plugins#docusauruspreset-classic for more information on how to configure individual plugins.`,
    );
  }

  return {themes, plugins};
}

export type {Options, ThemeConfig};

View on GitHub (pinned to 3f483e80e3)