{"record":{"id":"662e1c6f1d20f115","repo":"facebook/docusaurus","slug":"cannot-get-valid-docusaurus-webpack-compiler-name","errorCode":null,"errorMessage":"Cannot get valid Docusaurus webpack compiler name. Found compilerName=${compilerName}","messagePattern":"Cannot get valid Docusaurus webpack compiler name\\. Found compilerName=(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-utils/src/webpackUtils.ts","lineNumber":27,"sourceCode":"import {escapePath} from './pathUtils';\nimport {\n  WEBPACK_URL_LOADER_LIMIT,\n  OUTPUT_STATIC_ASSETS_DIR_NAME,\n} from './constants';\nimport type {RuleSetRule, LoaderContext} from 'webpack';\n\nexport type WebpackCompilerName = 'server' | 'client';\n\nexport function getWebpackLoaderCompilerName(\n  context: LoaderContext<unknown>,\n): WebpackCompilerName {\n  const compilerName = context._compiler?.name;\n  switch (compilerName) {\n    case 'server':\n    case 'client':\n      return compilerName;\n    default:\n      throw new Error(\n        `Cannot get valid Docusaurus webpack compiler name. Found compilerName=${compilerName}`,\n      );\n  }\n}\n\ntype AssetFolder = 'images' | 'files' | 'fonts' | 'medias';\n\ntype FileLoaderUtils = {\n  loaders: {\n    file: (options: {folder: AssetFolder}) => RuleSetRule;\n    url: (options: {folder: AssetFolder}) => RuleSetRule;\n    inlineMarkdownImageFileLoader: string;\n    inlineMarkdownAssetImageFileLoader: string;\n    inlineMarkdownLinkFileLoader: string;\n  };\n  rules: {\n    images: () => RuleSetRule;\n    svgs: () => RuleSetRule;","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-utils/src/webpackUtils.ts#L9-L45","documentation":"Thrown by getWebpackLoaderCompilerName when context._compiler.name is neither 'server' nor 'client'. Docusaurus runs two webpack compilers (named exactly 'server' and 'client') and its custom loaders rely on that to pick compiler-specific behavior. Any other name means the loader was attached to a compiler Docusaurus does not recognize.","triggerScenarios":"A user webpack config (custom plugin/rule) creates an additional compiler, or a loader is somehow invoked under a third-party compiler whose name differs. Also possible when bundler abstraction internals change name between Docusaurus versions.","commonSituations":"Custom docusaurus.config.js webpack chain that mutates compiler configuration, experimental Rspack/Webpack5 abstractions, or running a Docusaurus loader standalone outside its compiler.","solutions":["Avoid introducing extra named compilers in configureWebpack; reuse the existing client/server compilers.","If you need a custom loader, ensure it is only attached to Docusaurus's own client/server compiler rules.","Check for version mismatch between docusaurus and docusaurus-bundler after an upgrade."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":null,"typeGuard":"import type {LoaderContext} from 'webpack';\nfunction isDocusaurusCompilerName(name: unknown): name is 'server' | 'client' {\n  return name === 'server' || name === 'client';\n}","tryCatchPattern":null,"preventionTips":["Do not introduce additional named compilers in your webpack customization.","Attach custom loaders only to Docusaurus's own client/server rules.","Keep docusaurus and docusaurus-bundler on compatible versions."],"tags":["webpack","bundler","compiler","loader"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}