microsoft/playwright · error · Error

${name}: expected one of (load|domcontentloaded|networkidle|

Error message

${name}: expected one of (load|domcontentloaded|networkidle|commit)

What it means

Thrown by the verifyLifecycle() helper when a lifecycle event string is not one of the four valid values. The valid set is defined in types.kLifecycleEvents as { 'load', 'domcontentloaded', 'networkidle', 'commit' }. The function also maps 'networkidle0' (Puppeteer-compatible) to 'networkidle' before validation.

Source

Thrown at packages/playwright-core/src/server/frames.ts:1940

    });
  }

  retain() {
    ++this._protectCount;
  }

  release() {
    --this._protectCount;
    if (!this._protectCount)
      this._promise.resolve();
  }
}

function verifyLifecycle(name: string, waitUntil: types.LifecycleEvent): types.LifecycleEvent {
  if (waitUntil as unknown === 'networkidle0')
    waitUntil = 'networkidle';
  if (!types.kLifecycleEvents.has(waitUntil))
    throw new Error(`${name}: expected one of (load|domcontentloaded|networkidle|commit)`);
  return waitUntil;
}

function renderUnexpectedValue(expression: string, received: any): string {
  if (expression === 'to.match.aria')
    return received ? received.raw : received;
  return received;
}

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Use one of the four valid lifecycle events: 'load', 'domcontentloaded', 'networkidle', or 'commit'.
2. If migrating from Puppeteer, note that 'networkidle0' is accepted (mapped automatically), but 'domcontentloaded' uses lowercase 'd'.
3. Define lifecycle events as constants or use TypeScript's LiteralString union types to prevent typos.

Example fix

// before
await page.goto(url, { waitUntil: 'DOMContentLoaded' }); // wrong case

// after
await page.goto(url, { waitUntil: 'domcontentloaded' });

const VALID_LIFECYCLE = new Set(['load', 'domcontentloaded', 'networkidle', 'commit']);
function validateLifecycle(event) {
  if (!VALID_LIFECYCLE.has(event))
    throw new Error(`Invalid lifecycle: ${event}. Use one of: load, domcontentloaded, networkidle, commit`);
}

function isLifecycleEvent(value: string): value is 'load' | 'domcontentloaded' | 'networkidle' | 'commit' {
  return ['load', 'domcontentloaded', 'networkidle', 'commit'].includes(value);
}

When it happens

Trigger: Passing an invalid waitUntil value to page.goto(), page.waitForLoadState(), page.setContent(), page.reload(), or frame.goto(). Examples include typos like 'domContentLoaded' (wrong case), 'network Idle', 'loaded', or values from other tools like 'interactive' or 'complete'.

Common situations: Typo in the waitUntil option string. Using document.readyState values ('interactive', 'complete') which are NOT valid Playwright lifecycle events. Migrating from Puppeteer and using 'load2' or other non-standard values. Passing a variable that has an undefined or wrong value.

Related errors

• Frame has been detached.
• ${path}: no object with guid ${guid}
• "referer" is already specified as extra HTTP header
• Unable to retrieve content because the page is navigating an
• Provide an object with a `url`, `path` or `content` property

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