facebook/docusaurus · error

Cannot get valid Docusaurus webpack compiler name. Found com

Error message

Cannot get valid Docusaurus webpack compiler name. Found compilerName=${compilerName}

What it means

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.

Source

Thrown at packages/docusaurus-utils/src/webpackUtils.ts:27

import {escapePath} from './pathUtils';
import {
  WEBPACK_URL_LOADER_LIMIT,
  OUTPUT_STATIC_ASSETS_DIR_NAME,
} from './constants';
import type {RuleSetRule, LoaderContext} from 'webpack';

export type WebpackCompilerName = 'server' | 'client';

export function getWebpackLoaderCompilerName(
  context: LoaderContext<unknown>,
): WebpackCompilerName {
  const compilerName = context._compiler?.name;
  switch (compilerName) {
    case 'server':
    case 'client':
      return compilerName;
    default:
      throw new Error(
        `Cannot get valid Docusaurus webpack compiler name. Found compilerName=${compilerName}`,
      );
  }
}

type AssetFolder = 'images' | 'files' | 'fonts' | 'medias';

type FileLoaderUtils = {
  loaders: {
    file: (options: {folder: AssetFolder}) => RuleSetRule;
    url: (options: {folder: AssetFolder}) => RuleSetRule;
    inlineMarkdownImageFileLoader: string;
    inlineMarkdownAssetImageFileLoader: string;
    inlineMarkdownLinkFileLoader: string;
  };
  rules: {
    images: () => RuleSetRule;
    svgs: () => RuleSetRule;

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Avoid introducing extra named compilers in configureWebpack; reuse the existing client/server compilers.
2. If you need a custom loader, ensure it is only attached to Docusaurus's own client/server compiler rules.
3. Check for version mismatch between docusaurus and docusaurus-bundler after an upgrade.

import type {LoaderContext} from 'webpack';
function isDocusaurusCompilerName(name: unknown): name is 'server' | 'client' {
  return name === 'server' || name === 'client';
}

When it happens

Trigger: 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.

Common situations: Custom docusaurus.config.js webpack chain that mutates compiler configuration, experimental Rspack/Webpack5 abstractions, or running a Docusaurus loader standalone outside its compiler.

Related errors

• Docusaurus built-in SVG rule couldn't be found. The SVGR plu
• To enable Docusaurus Faster options, your site must add the
• You can't use siteConfig.webpack.jsLoader and siteConfig.fut
• HTML minification failed (Terser)
• HTML minification failed (SWC)

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