facebook/docusaurus · critical · Error

Docusaurus Bug: server bundle export from "${filename}" must

Error message

Docusaurus Bug: server bundle export from "${filename}" must be a function that renders the Docusaurus React app, not ${typeof serverEntry?.default}

What it means

Thrown by `ssgRenderer` when the evaluated server bundle does not export a `default` function. The renderer evaluates the compiled server entry and expects `serverEntry.default` to be a render function returning the app's HTML. The 'Docusaurus Bug' prefix signals an internal/framework-level failure rather than user config.

Source

Thrown at packages/docusaurus/src/ssg/ssgRenderer.ts:89

    // This uses module.createRequire() instead of very old "require-like" lib
    // See also: https://github.com/pierrec/node-eval/issues/33
    require: ssgRequire.require,
  };

  const serverEntry = await PerfLogger.async(
    `Evaluate server bundle`,
    () =>
      evaluate(
        source,
        /* filename: */ filename,
        /* scope: */ globals,
        /* includeGlobals: */ true,
      ) as {default?: AppRenderer},
  );

  if (!serverEntry?.default || typeof serverEntry.default !== 'function') {
    throw new Error(
      `Docusaurus Bug: server bundle export from "${filename}" must be a function that renders the Docusaurus React app, not ${typeof serverEntry?.default}`,
    );
  }

  async function shutdown() {
    ssgRequire.cleanup();
  }

  return {
    render: serverEntry.default,
    shutdown,
  };
}

export type SSGRenderer = {
  shutdown: () => Promise<void>;
  renderPathnames: (pathnames: string[]) => Promise<SSGResult[]>;
};

View on GitHub (pinned to 3f483e80e3)

Solutions

Clear build caches: `pnpm clear` / remove `.docusaurus` and `node_modules/.cache`.
Rebuild theme/core packages: `pnpm build:packages`.
Disable any custom `siteConfig.plugins`/aliases that override the server entry and retry.
If reproducing on a fresh project, file a Docusaurus bug with the server bundle file (the message names it).

Example fix

// before (custom theme server entry)
export const render = () => '<html/>'; // named, not default
// after
export default function render() { return '<html/>'; }

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate a custom server entry exports a default function:
const mod = require('./serverEntry.js');
if (typeof mod.default !== 'function') throw new Error('server entry must export default function');

Type guard

function isAppRenderer(v: unknown): v is (props: any) => Promise<string> {
  return typeof v === 'function';
}

Try / catch

try {
  const {render, shutdown} = await renderSSG();
} catch (e) {
  if (/Docusaurus Bug: server bundle export/.test(e.message)) {
    await clearCacheAndRebuild();
  }
  throw e;
}

Prevention

Avoid overriding the server entry unless absolutely necessary.
Clear `.docusaurus` after upgrading theme/core.
Rebuild all `@docusaurus/*` packages together (`pnpm build:packages`).

When it happens

Trigger: The server bundle's entry module has no `export default function render(...)` or the default export is not a function (e.g. an object). The check at ssgRenderer.ts:86-92 fires when `!serverEntry?.default || typeof serverEntry.default !== 'function'`.

Common situations: A custom theme/server entry override that omits the default export; a corrupted/incomplete build of the bundler output; an incompatible theme version overriding the SSR template; a broken alias resolving the server entry to the wrong file.

Related errors

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