facebook/docusaurus · error

Docusaurus built-in SVG rule couldn't be found. The SVGR plu

Error message

Docusaurus built-in SVG rule couldn't be found. The SVGR plugin can't enhance it.

What it means

Thrown by enhanceConfig in the SVGR plugin when it cannot find Docusaurus's built-in webpack SVG rule to wrap. The plugin works by locating the existing rule (matched by String(r.test) === String(utils.rules.svgs().test)) and replacing it with a oneOf that adds @svgr/webpack for React/JSX/MDX issuers. If the rule is absent (custom webpack config removed/renamed it), enhancement cannot proceed.

Source

Thrown at packages/docusaurus-plugin-svgr/src/svgrLoader.ts:61

    ...params.svgrConfig,
  };
  return {
    loader: require.resolve('@svgr/webpack'),
    options,
  };
}

export function enhanceConfig(config: Configuration, params: Params): void {
  const utils = getFileLoaderUtils(params.isServer);

  const rules = config?.module?.rules as RuleSetRule[];

  const existingSvgRule: RuleSetRule = (() => {
    const rule = rules.find(
      (r) => String(r.test) === String(utils.rules.svgs().test),
    );
    if (!rule) {
      throw new Error(
        "Docusaurus built-in SVG rule couldn't be found. The SVGR plugin can't enhance it.",
      );
    }
    return rule;
  })();

  const newSvgRule: RuleSetRule = {
    test: /\.svg$/i,
    oneOf: [
      {
        use: [createSVGRRule(params)],
        // We don't want to use SVGR loader for non-React source code
        // ie we don't want to use SVGR for CSS files...
        issuer: {
          and: [/\.(?:tsx?|jsx?|mdx?)$/i],
        },
      },
      existingSvgRule,

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Avoid removing the default SVG rule in configureWebpack; merge rather than replace module.rules.
2. Ensure @docusaurus/plugin-svgr and @docusaurus/core versions are aligned (reinstall/pnpm install).
3. If you need custom SVG handling, keep a rule whose test matches utils.rules.svgs().test so the plugin can find it.
4. Move SVGR plugin registration after any rule-rewriting plugins.

const hasSvgRule = (config.module?.rules ?? []).some(r =>
  String(r.test) === String(getFileLoaderUtils(false).rules.svgs().test));
if (!hasSvgRule) {
  throw new Error('Default SVG rule missing; cannot enhance with SVGR');
}

When it happens

Trigger: A custom webpack config in docusaurus.config (configureWebpack) that mutates/removes the default SVG rule before the SVGR plugin runs; an outdated Docusaurus core whose rule test string differs; ordering where SVGR runs before core rules are registered.

Common situations: Overriding module.rules in configureWebpack and dropping the SVG rule; using a forked bundler (rspack) that serializes the test differently; version mismatch between plugin-svgr and docusaurus core; manually adding svg handling that shadows the default.

Related errors

• Cannot get valid Docusaurus webpack compiler name. Found com
• 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/6e2b4649f76def18. Report an issue: GitHub.