What causes "Failed to load init page "${initPage}": ${reason}" in microsoft/playwright?

Inspect e.cause for the original error from the init module.

microsoft/playwright · error · Error

Failed to load init page "${initPage}": ${reason}

Error message

Failed to load init page "${initPage}": ${reason}

What it means

Thrown by Tab._initialize when one of the user-configured browser.initPage modules cannot be required or its default export throws. The initPage entries are loaded with require(initPage) and called as func({ page }); any exception is wrapped with the failing module path and original message (cause set).

Source

Thrown at packages/playwright-core/src/tools/backend/tab.ts:186

    const errors = await page.pageErrors().catch(() => []);
    for (const error of errors)
      result.push(pageErrorToConsoleMessage(error));
    return result;
  }

  private async _initialize() {
    for (const message of await Tab.collectConsoleMessages(this.page))
      this._handleConsoleMessage(message);
    const requests = await this.page.requests().catch(() => []);
    for (const request of requests.filter(r => r.existingResponse() || r.failure()))
      this._requests.push(request);
    for (const initPage of this.context.config.browser?.initPage || []) {
      try {
        const { default: func } = require(initPage);
        await func({ page: this.page });
      } catch (e) {
        const reason = e instanceof Error ? e.message : String(e);
        throw new Error(`Failed to load init page "${initPage}": ${reason}`, { cause: e });
      }
    }
  }

  modalStates(): ModalState[] {
    return this._modalStates;
  }

  setModalState(modalState: ModalState) {
    this._modalStates.push(modalState);
    this.emit(TabEvents.modalState, modalState);
  }

  clearModalState(modalState: ModalState) {
    this._modalStates = this._modalStates.filter(state => state !== modalState);
  }

  private _dialogShown(dialog: playwright.Dialog) {

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Inspect e.cause for the original error from the init module.
Run the init module standalone against a fresh page to reproduce, then fix the script.
Confirm the initPage value resolves via Node's require resolution from the working directory.
Temporarily remove the failing entry from browser.initPage to isolate the failure.

Example fix

// before - init script throws
// init.js: export default async ({ page }) => { await page.evaluate(() => window.x = undefinedFn()); };
// config: browser.initPage = ['./init.js']

// after
export default async ({ page }) => {
  await page.addInitScript(() => { window.x = 1; });
};

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate each initPage entry resolves before the context is created.
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
function validateInitPages(entries: string[]) {
  for (const e of entries) {
    const mod = require(e);
    if (typeof mod.default !== 'function')
      throw new Error(`initPage '${e}' has no default function export`);
  }
}

Type guard

function isInitFunction(x: unknown): x is (arg: { page: import('playwright-core').Page }) => Promise<void> {
  return typeof x === 'function';
}

Try / catch

try {
  await context.ensureBrowserContext(); // triggers Tab._initialize
} catch (e) {
  const cause = (e as Error & { cause?: Error }).cause;
  if (e instanceof Error && e.message.startsWith('Failed to load init page')) {
    // inspect cause, disable the offending initPage entry, retry
  } else throw e;
}

Prevention

Keep initPage modules side-effect free and resilient to about:blank.
Test each initPage function against a fresh page in isolation.
Use page.addInitScript for one-shot DOM injection rather than imperative code that can throw.

When it happens

Trigger: Configuring context.browser.initPage to a path that does not exist, exports no default function, or whose default function throws during page setup (e.g. page.evaluate failure).

Common situations: Custom init scripts that mutate every new page (auth injection, polyfills); a typo in the initPage path; an init script written for a different Playwright API surface; the script throws on about:blank before navigation.

Related errors

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/a320c1127df487f8. Report an issue: GitHub.