{"record":{"id":"ca118b4fae2c51c0","repo":"facebook/docusaurus","slug":"the-css-cascade-layers-plugin-does-not-support-mul","errorCode":null,"errorMessage":"The CSS Cascade Layers plugin does not support multiple instances.","messagePattern":"The CSS Cascade Layers plugin does not support multiple instances\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-css-cascade-layers/src/index.ts","lineNumber":27,"sourceCode":"import {PostCssPluginWrapInLayer} from './postCssPlugin';\nimport {generateLayersDeclaration} from './layers';\nimport type {LoadContext, Plugin} from '@docusaurus/types';\nimport type {PluginOptions, Options} from './options';\n\nconst PluginName = 'docusaurus-plugin-css-cascade-layers';\n\nconst LayersDeclarationModule = 'layers.css';\n\nfunction getLayersDeclarationPath(\n  context: LoadContext,\n  options: PluginOptions,\n) {\n  const {generatedFilesDir} = context;\n  const pluginId = options.id;\n  if (pluginId !== 'default') {\n    // Since it's only possible to declare a single layer order\n    // using this plugin twice doesn't really make sense\n    throw new Error(\n      'The CSS Cascade Layers plugin does not support multiple instances.',\n    );\n  }\n  return path.join(\n    generatedFilesDir,\n    PluginName,\n    pluginId,\n    LayersDeclarationModule,\n  );\n}\n\nexport default function pluginCssCascadeLayers(\n  context: LoadContext,\n  options: PluginOptions,\n): Plugin | null {\n  const layersDeclarationPath = getLayersDeclarationPath(context, options);\n\n  return {","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-css-cascade-layers/src/index.ts#L9-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nplugins: [\n  ['@docusaurus/plugin-css-cascade-layers', {id: 'custom'}],\n]\n// after\nplugins: [\n  '@docusaurus/plugin-css-cascade-layers',\n]","handlingStrategy":"validation","validationCode":"const cascadePlugins = (config.plugins ?? []).filter(p =>\n  (Array.isArray(p) ? p[0] : p) === '@docusaurus/plugin-css-cascade-layers');\nif (cascadePlugins.length > 1) {\n  throw new Error('css-cascade-layers registered multiple times');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["css","cascade-layers","plugin-instance","config-validation"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}