You site uses the Vercel Analytics plugin with a custom plug

Error message

You site uses the Vercel Analytics plugin with a custom plugin id (name=${options.id}).
      But this plugin is only supposed to be used at most once per site. Therefore providing a custom plugin id is unsupported.

What it means

Thrown by ensureNoMultiInstance in plugin-vercel-analytics when the plugin is registered with an id other than DEFAULT_PLUGIN_ID ('default'). Vercel Analytics injects a single global script, so multiple instances are unsupported and a custom id (which Docusaurus uses to disambiguate multi-instance plugins) is rejected at option validation time. The message is built with logger.interpolate to highlight the offending id.

Source

Thrown at packages/docusaurus-plugin-vercel-analytics/src/options.ts:29

export type PluginOptions = {
  id: string;
  mode: 'auto' | 'production' | 'development' | undefined;
  debug: boolean | undefined;
};

export type Options = Partial<PluginOptions>;

const pluginOptionsSchema = Joi.object<PluginOptions>({
  mode: Joi.string().valid('auto', 'production', 'development').optional(),
  debug: Joi.boolean().optional(),
});

// We can't validate this through the schema
// Docusaurus core auto registers the id field to the schema already
function ensureNoMultiInstance(options: Options) {
  if (options?.id && options.id !== DEFAULT_PLUGIN_ID) {
    throw new Error(
      logger.interpolate`You site uses the Vercel Analytics plugin with a custom plugin id (name=${options.id}).
      But this plugin is only supposed to be used at most once per site. Therefore providing a custom plugin id is unsupported.`,
    );
  }
}

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

View on GitHub (pinned to 3f483e80e3)

Solutions

Register the plugin once without an id (let it default).
Remove the duplicate registration if it appears in both presets and plugins.
Rebuild to confirm.

Example fix

// before
plugins: [
  ['@docusaurus/plugin-vercel-analytics', { id: 'analytics2' }],
]
// after
plugins: [
  '@docusaurus/plugin-vercel-analytics',
]

Defensive patterns

Strategy: validation

Validate before calling

const vaPlugins = (config.plugins ?? []).filter(p =>
  (Array.isArray(p) ? p[0] : p) === '@docusaurus/plugin-vercel-analytics');
if (vaPlugins.some(p => Array.isArray(p) && p[1]?.id && p[1].id !== 'default')) {
  throw new Error('vercel-analytics must use the default id');
}

Prevention

Treat analytics plugins as single-instance; never assign a custom id.
Review both presets and plugins arrays for duplicates.

When it happens

Trigger: Registering the plugin twice, or once with an explicit id: ['@docusaurus/plugin-vercel-analytics', {id:'secondary'}].

Common situations: Copy-pasting a multi-instance registration pattern; programmatic config generation that auto-assigns ids; misunderstanding that this analytics plugin is inherently single-instance.

Related errors

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