facebook/docusaurus · error

Docusaurus could not load module at path path=${modulePath}

Error message

Docusaurus could not load module at path path=${modulePath}

What it means

Thrown by loadFreshModule() when jiti.import() rejects while trying to load a module. jiti is Docusaurus's loader for ESM, CJS, JSON, and TypeScript files (used so user config and plugin files can be authored in any of those formats). The underlying rejection — syntax error, missing file, missing dependency, bad export — is attached as {cause: error} so the real failure is preserved.

Source

Thrown at packages/docusaurus-utils/src/moduleUtils.ts:57

      default: options?.default,
    });

    if (DEBUG) {
      console.log('Jiti module loaded', {
        modulePath,
        options,
        type: typeof module,
        keys:
          module && typeof module === 'object'
            ? Object.keys(module)
            : undefined,
        module,
      });
    }

    return module;
  } catch (error) {
    throw new Error(
      logger.interpolate`Docusaurus could not load module at path path=${modulePath}`,
      {cause: error},
    );
  }
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Read the cause property of the thrown error — it carries the original jiti/compile error with file and line.
2. Fix the reported syntax/import error in the offending module, then rebuild.
3. If the cause is a missing dependency, install it (pnpm install <dep>) and confirm it resolves.
4. If options.default was set but the module has no default export, either add a default export to the module or drop the options.default flag.

Example fix

// before — plugin file uses an uninstalled import
import { foo } from 'not-installed-pkg';
export default function plugin() { /* ... */ }

// after
// pnpm add not-installed-pkg
import { foo } from 'not-installed-pkg';
export default function plugin() { /* ... */ }

import fs from 'fs-extra';

async function modulePathLooksValid(modulePath: string): Promise<boolean> {
  // basic existence check for relative/absolute file paths; not exhaustive
  return modulePath.startsWith('.') ? fs.pathExists(modulePath) : true;
}

try {
  await loadFreshModule(modulePath, options);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Docusaurus could not load module')) {
    // err.cause is the original jiti error: TS compile error, missing dep, etc.
    console.error(err.cause);
  }
  throw err;
}

When it happens

Trigger: Loading a docusaurus.config.ts / plugin file / theme component via loadFreshModule where the module has a TypeScript compile error, a missing import, a SyntaxError, exports something jiti cannot interop, or simply does not exist at the resolved path.

Common situations: A syntax error in docusaurus.config.ts or a plugin .ts file. Importing a dependency that is not installed (npm install was incomplete). An ESM/CJS interop mismatch where the module has no default export but options.default was set. A path alias that jiti does not resolve. Upgrading a dependency that changed its export shape.

Related errors

• Invalid module path of type "name=${typeof modulePath}" with
• You can't use siteConfig.webpack.jsLoader and siteConfig.fut
• Unexpected "reportingSeverity" value: ${reportingSeverity}.
• ${JSON.stringify(redirect)} => Validation error: ${error.mes
• Can't reference blog post authors by a key (such as '${key}'

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