In Docusaurus v4, the Google Analytics plugin has been remov

Error message

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

What it means

Thrown by preset-classic when a 'googleAnalytics' key is present in either the preset options or themeConfig. The standalone Google Analytics plugin was removed in Docusaurus v4; users must migrate to plugin-google-gtag (gtag) or plugin-google-tag-manager (googleTagManager). Marked TODO for removal in v5, this is the v4 deprecation enforcement.

Source

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

    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[] = [];

  // TODO Docusaurus v4: temporary due to the opt-in flag
  // In v4 we'd like to use layers everywhere natively
  if (siteConfig.future.v4.useCssCascadeLayers) {
    plugins.push(makePluginConfig('@docusaurus/plugin-css-cascade-layers'));
  }

  if (docs !== false) {

View on GitHub (pinned to 3f483e80e3)

Solutions

Replace googleAnalytics with gtag (recommended for GA4) under preset options: presets: [['classic', { gtag: { trackingID: 'G-XXX' } }]].
Or use googleTagManager if you rely on GTM: presets: [['classic', { googleTagManager: { containerId: 'GTM-XXX' } }]].
Remove the googleAnalytics key from both preset options and themeConfig; rebuild.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

const hasGA = 'googleAnalytics' in (presetOptions ?? {}) || 'googleAnalytics' in (siteConfig.themeConfig ?? {});
if (hasGA) throw new Error('googleAnalytics removed in v4; use gtag or googleTagManager');

Prevention

When upgrading to v4, migrate analytics as part of the upgrade checklist.
Prefer GA4 gtag over the legacy googleAnalytics key.

When it happens

Trigger: Carrying over themeConfig.googleAnalytics or preset option googleAnalytics from a v3 (or earlier) config after upgrading to v4.

Common situations: Running the v3->v4 upgrade without migrating analytics; copying a v3 docusaurus.config; using a starter template that still references googleAnalytics.

Related errors

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