microsoft/playwright · error · Error

clientCertificates.origin is required

Error message

clientCertificates.origin is required

What it means

`verifyClientCertificates` requires each client-certificate entry to have an `origin` (the host the cert applies to). Without origin, Playwright can't match the certificate to outgoing requests.

Source

Thrown at packages/playwright-core/src/server/browserContext.ts:800

export function verifyGeolocation(geolocation?: types.Geolocation): asserts geolocation is types.Geolocation {
  if (!geolocation)
    return;
  geolocation.accuracy = geolocation.accuracy || 0;
  const { longitude, latitude, accuracy } = geolocation;
  if (longitude < -180 || longitude > 180)
    throw new Error(`geolocation.longitude: precondition -180 <= LONGITUDE <= 180 failed.`);
  if (latitude < -90 || latitude > 90)
    throw new Error(`geolocation.latitude: precondition -90 <= LATITUDE <= 90 failed.`);
  if (accuracy < 0)
    throw new Error(`geolocation.accuracy: precondition 0 <= ACCURACY failed.`);
}

export function verifyClientCertificates(clientCertificates?: types.BrowserContextOptions['clientCertificates']) {
  if (!clientCertificates)
    return;
  for (const cert of clientCertificates) {
    if (!cert.origin)
      throw new Error(`clientCertificates.origin is required`);
    if (!cert.cert && !cert.key && !cert.passphrase && !cert.pfx)
      throw new Error('None of cert, key, passphrase or pfx is specified');
    if (cert.cert && !cert.key)
      throw new Error('cert is specified without key');
    if (!cert.cert && cert.key)
      throw new Error('key is specified without cert');
    if (cert.pfx && (cert.cert || cert.key))
      throw new Error('pfx is specified together with cert, key or passphrase');
  }
}

export function normalizeProxySettings(proxy: types.ProxySettings): types.ProxySettings {
  let { server, bypass } = proxy;
  let url;
  try {
    // new URL('127.0.0.1:8080') throws
    // new URL('localhost:8080') fails to parse host or protocol
    // In both of these cases, we need to try re-parse URL with `http://` prefix.

View on GitHub (pinned to c8fc3bf8d3)

Solutions

  1. Add `origin: 'https://host'` to each clientCertificates entry
  2. Group cert/key/passphrase/pfx under the correct origin
  3. Validate each entry has origin before launching the context

Example fix

// before
await browser.newContext({
  clientCertificates: [{ cert: 'c.pem', key: 'k.pem' }]
});

// after
await browser.newContext({
  clientCertificates: [{ origin: 'https://example.com', cert: 'c.pem', key: 'k.pem' }]
});
Defensive patterns

Strategy: validation

Validate before calling

function validateClientCerts(certs?: { origin?: string; cert?: string; key?: string; passphrase?: string; pfx?: string }[]) {
  if (!certs) return;
  for (const c of certs) {
    if (!c.origin) throw new Error('Each clientCertificates entry requires an `origin` (e.g. https://host).');
    if (!c.cert && !c.key && !c.passphrase && !c.pfx)
      throw new Error(`clientCertificates entry for ${c.origin} has no cert/key/passphrase/pfx`);
    if (c.cert && !c.key) throw new Error(`cert requires key for ${c.origin}`);
    if (!c.cert && c.key) throw new Error(`key requires cert for ${c.origin}`);
    if (c.pfx && (c.cert || c.key)) throw new Error(`pfx is exclusive of cert/key for ${c.origin}`);
  }
}
validateClientCerts(opts.clientCertificates);
await browser.newContext(opts);

Type guard

function isValidCertEntry(c: unknown): c is { origin: string; cert?: string; key?: string; passphrase?: string; pfx?: string } {
  return !!c && typeof c === 'object' && typeof (c as any).origin === 'string' && (c as any).origin.length > 0;
}

Prevention

When it happens

Trigger: `browser.newContext({ clientCertificates: [{ cert: '...', key: '...' }] })` — an entry missing the `origin` field.

Common situations: Incomplete TLS client-auth configs; assuming Playwright applies certs globally rather than per-origin; partial refactor of cert loading.

Understand the failure class

Related errors

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