angular/angular-cli · error · Error

A module or bootstrap option must be provided.

Error message

A module or bootstrap option must be provided.

What it means

CommonEngine.renderApplication needs an Angular module or bootstrap function to render the app server-side. If neither 'bootstrap' in the CommonEngineRenderOptions nor a bootstrap in the engine options is provided, rendering cannot proceed and an Error is thrown.

Source

Thrown at packages/angular/ssr/node/src/common-engine/common-engine.ts:190

      return undefined;
    }

    // Static file exists.
    const content = await fs.promises.readFile(pagePath, 'utf-8');
    const isSSG = SSG_MARKER_REGEXP.test(content);
    if (isSSG) {
      this.pageIsSSG.set(pagePath, true);

      return content;
    }

    return undefined;
  }

  private async renderApplication(opts: CommonEngineRenderOptions): Promise<string> {
    const moduleOrFactory = this.options?.bootstrap ?? opts.bootstrap;
    if (!moduleOrFactory) {
      throw new Error('A module or bootstrap option must be provided.');
    }

    const extraProviders: StaticProvider[] = [
      { provide: ɵSERVER_CONTEXT, useValue: 'ssr' },
      ...(opts.providers ?? []),
      ...(this.options?.providers ?? []),
    ];

    let document = opts.document;
    if (!document && opts.documentFilePath) {
      document = await this.getDocument(opts.documentFilePath);
    }

    const commonRenderingOptions = {
      url: opts.url,
      document,
      // Validation is already happened in the render method.
      allowedHosts: ['*'],

View on GitHub (pinned to bb72145f9a)

Solutions

1. Pass bootstrap to CommonEngine options: new CommonEngine(AppServerModule, opts) or render({ bootstrap: AppServerModule })
2. In Angular 17+ SSR setups, pass the bootstrap function from app.config.server: { bootstrap: bootstrapApplication } pattern per docs
3. Check server.ts matches the generated template from ng add @angular/ssr
4. Verify the imported AppServerModule is not undefined due to a bad import path

Example fix

// before
const engine = new CommonEngine();
export const reqHandler = engine.getHandler({ });
// after
import { AppServerModule } from './src/main.server';
const engine = new CommonEngine();
export const reqHandler = engine.getHandler({ bootstrap: AppServerModule });

import { AppServerModule } from './src/main.server';
if (!AppServerModule) {
  throw new Error('main.server export missing; fix import before creating CommonEngine');
}
const engine = new CommonEngine();
export const reqHandler = engine.getHandler({ bootstrap: AppServerModule });

function hasBootstrap(o: Partial<{ bootstrap: unknown }>): o is { bootstrap: NonNullable<unknown> } {
  return o.bootstrap != null;
}

try {
  html = await engine.render({ bootstrap: AppServerModule, ...opts });
} catch (e) {
  if (e instanceof Error && e.message.includes('A module or bootstrap option must be provided')) {
    console.error('CommonEngine options must include bootstrap: AppServerModule');
  }
  throw e;
}

When it happens

Trigger: Calling new CommonEngine().render(...) or renderApplication(...) without passing { bootstrap } in options, or a server.ts where the bootstrap option was removed/renamed during SSR migration.

Common situations: Upgrading Angular SSR versions where the option moved, hand-written server.ts missing the bootstrap export, custom SSR setups passing only template/providers.

Related errors

• Configuration error: found 'withAppShell()' without 'withRou
• "${TRUST_ALL_PROXY_HEADERS}" is not allowed as a value for t
• "${header}" is not a valid proxy header. Trusted proxy heade
• Cannot find 'options' for ${projectName} ${target} target.
• No project name provided and no default project found in wor

AI-assisted analysis of angular/angular-cli@bb72145f9a (2026-08-30). Data as JSON: /api/errors/0fdce636f57fa8f4. Report an issue: GitHub.