The "gtag" field in themeConfig should now be specified as o

Error message

The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. For preset-classic, simply move themeConfig.gtag to preset options. More information at https://github.com/facebook/docusaurus/pull/5832.

What it means

Thrown by the preset-classic function when a 'gtag' key exists in themeConfig. It is the preset-level counterpart of the plugin's own guard: preset-classic detects the legacy themeConfig.gtag location and instructs the user to move it to preset options. This runs before plugins are constructed so users get an actionable message early.

Source

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

    debug,
    docs,
    blog,
    pages,
    sitemap,
    svgr,
    theme,
    gtag,
    googleTagManager,
    ...rest
  } = opts;

  const themes: PluginConfig[] = [];
  themes.push(makePluginConfig('@docusaurus/theme-classic', theme));
  if (algolia) {
    themes.push(require.resolve('@docusaurus/theme-search-algolia'));
  }
  if ('gtag' in themeConfig) {
    throw new Error(
      'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. For preset-classic, simply move themeConfig.gtag to preset options. More information at https://github.com/facebook/docusaurus/pull/5832.',
    );
  }

  // TODO Docusaurus v5: remove
  if ('googleAnalytics' in opts || 'googleAnalytics' in themeConfig) {
    throw new Error(
      `In Docusaurus v4, the Google Analytics plugin has been removed.
You can now use either:
- @docusaurus/plugin-google-gtag - presetOptions.gtag
- @docusaurus/plugin-google-tag-manager - presetOptions.googleTagManager

See also: https://github.com/facebook/docusaurus/issues/7221`,
    );
  }

  const plugins: PluginConfig[] = [];

View on GitHub (pinned to 3f483e80e3)

Solutions

Move the gtag config from themeConfig into the preset options: presets: [['classic', { gtag: {...} }]].
Remove themeConfig.gtag entirely.
Rebuild.

Example fix

// before
presets: [['classic', {}]],
themeConfig: { gtag: { trackingID: 'G-XXX' } }
// after
presets: [['classic', { gtag: { trackingID: 'G-XXX' } }]],

Defensive patterns

Strategy: validation

Validate before calling

if ('gtag' in siteConfig.themeConfig) {
  throw new Error('Move themeConfig.gtag to preset options (presets classic.gtag)');
}

Prevention

Centralize analytics config under preset options, not themeConfig.
After upgrades, grep docusaurus.config for relocated keys.

When it happens

Trigger: Configuring themeConfig: { gtag: {...} } while using @docusaurus/preset-classic.

Common situations: Upgrading from a Docusaurus version where gtag was configured under themeConfig; outdated docs/tutorials; partial migration.

Related errors

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