The CSS Cascade Layers plugin does not support multiple inst

Error message

The CSS Cascade Layers plugin does not support multiple instances.

What it means

Thrown by getLayersDeclarationPath in the CSS Cascade Layers plugin when the plugin instance's id is not 'default'. Because a single global layer order (layers.css) must be declared for the whole site, running this plugin more than once (each instance gets a distinct id from Docusaurus) is meaningless and rejected.

Source

Thrown at packages/docusaurus-plugin-css-cascade-layers/src/index.ts:27

import {PostCssPluginWrapInLayer} from './postCssPlugin';
import {generateLayersDeclaration} from './layers';
import type {LoadContext, Plugin} from '@docusaurus/types';
import type {PluginOptions, Options} from './options';

const PluginName = 'docusaurus-plugin-css-cascade-layers';

const LayersDeclarationModule = 'layers.css';

function getLayersDeclarationPath(
  context: LoadContext,
  options: PluginOptions,
) {
  const {generatedFilesDir} = context;
  const pluginId = options.id;
  if (pluginId !== 'default') {
    // Since it's only possible to declare a single layer order
    // using this plugin twice doesn't really make sense
    throw new Error(
      'The CSS Cascade Layers plugin does not support multiple instances.',
    );
  }
  return path.join(
    generatedFilesDir,
    PluginName,
    pluginId,
    LayersDeclarationModule,
  );
}

export default function pluginCssCascadeLayers(
  context: LoadContext,
  options: PluginOptions,
): Plugin | null {
  const layersDeclarationPath = getLayersDeclarationPath(context, options);

  return {

View on GitHub (pinned to 3f483e80e3)

Solutions

Register the plugin only once, without a custom id (or omit it so Docusaurus uses 'default').
If preset-classic already enables cascade layers (future.v4.useCssCascadeLayers), do not also add the plugin manually.
Remove the duplicate entry and rebuild.

Example fix

// before
plugins: [
  ['@docusaurus/plugin-css-cascade-layers', {id: 'custom'}],
]
// after
plugins: [
  '@docusaurus/plugin-css-cascade-layers',
]

Defensive patterns

Strategy: validation

Validate before calling

const cascadePlugins = (config.plugins ?? []).filter(p =>
  (Array.isArray(p) ? p[0] : p) === '@docusaurus/plugin-css-cascade-layers');
if (cascadePlugins.length > 1) {
  throw new Error('css-cascade-layers registered multiple times');
}

Prevention

Register css-cascade-layers at most once and never with a custom id.
Remember preset-classic adds it automatically when future.v4.useCssCascadeLayers is true.

When it happens

Trigger: Registering @docusaurus/plugin-css-cascade-layers twice, or once with an explicit id other than 'default' (e.g. [['plugin-css-cascade-layers', {id:'custom'}]]). Also triggered when presets auto-add it alongside a manual registration.

Common situations: Manually adding the plugin in docusaurus.config plugins while it's already added by preset-classic via the future.v4.useCssCascadeLayers flag; copy-pasting a multi-instance pattern used for docs/blog.

Related errors

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