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. More information at https://github.com/facebook/docusaurus/pull/5832.

What it means

Thrown by validateThemeConfig in plugin-google-gtag when a 'gtag' key is present in docusaurus.config themeConfig. The gtag configuration was moved out of themeConfig into the plugin's own options, so this guard rejects the old location and points to the migration PR. It fires during theme-config validation at startup.

Source

Thrown at packages/docusaurus-plugin-google-gtag/src/options.ts:56

      }),
      Joi.array().items(Joi.string().required()),
    )
    .required(),
  anonymizeIP: Joi.boolean().default(DEFAULT_OPTIONS.anonymizeIP),
});

export function validateOptions({
  validate,
  options,
}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
  return validate(pluginOptionsSchema, options);
}

export function validateThemeConfig({
  themeConfig,
}: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig {
  if ('gtag' in themeConfig) {
    throw new Error(
      'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. More information at https://github.com/facebook/docusaurus/pull/5832.',
    );
  }
  return themeConfig;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

Remove themeConfig.gtag and pass the same config (trackingID etc.) to the plugin in the plugins array or preset options.
For preset-classic, move it to the preset's gtag option.
Rebuild to confirm the error is gone.

Example fix

// before
themeConfig: { gtag: { trackingID: 'G-XXX' } }
// after
plugins: [
  ['@docusaurus/plugin-google-gtag', { trackingID: 'G-XXX' }],
]

Defensive patterns

Strategy: validation

Validate before calling

if ('gtag' in siteConfig.themeConfig) {
  throw new Error('Move themeConfig.gtag to plugin-google-gtag options');
}

Prevention

After upgrading Docusaurus, search the config for legacy themeConfig keys (gtag, googleAnalytics).
Keep analytics config under the owning plugin's options, not themeConfig.

When it happens

Trigger: Having themeConfig: { gtag: {...} } in docusaurus.config.js while also using @docusaurus/plugin-google-gtag.

Common situations: Upgrading from an older Docusaurus where gtag lived in themeConfig; following an outdated tutorial; partial migration that left the key behind.

Related errors

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