microsoft/playwright · error · Error

Invalid http credentials format: use "username:password", fo

Error message

Invalid http credentials format: use "username:password", for example --http-credentials="admin:secret"

What it means

Playwright's CLI (`playwright open`, `playwright cr`, etc.) throws this while converting the `--http-credentials` string option into the httpCredentials context option. The parser at browserActions.ts:131-139 splits on the first ':' to build {username, password}; if the value contains no colon at all, the format is unusable and it aborts before launching the browser.

Source

Thrown at packages/playwright-core/src/cli/browserActions.ts:134

  if (options.geolocation) {
    try {
      const [latitude, longitude] = options.geolocation.split(',').map(n => parseFloat(n.trim()));
      contextOptions.geolocation = {
        latitude,
        longitude
      };
    } catch (e) {
      throw new Error('Invalid geolocation format, should be "lat,long". For example --geolocation="37.819722,-122.478611"');
    }
    contextOptions.permissions = ['geolocation'];
  }

  // HTTP credentials

  if (options.httpCredentials) {
    const separator = options.httpCredentials.indexOf(':');
    if (separator === -1)
      throw new Error('Invalid http credentials format: use "username:password", for example --http-credentials="admin:secret"');
    contextOptions.httpCredentials = {
      username: options.httpCredentials.substring(0, separator),
      password: options.httpCredentials.substring(separator + 1),
    };
  }

  // User agent

  if (options.userAgent)
    contextOptions.userAgent = options.userAgent;

  // Lang

  if (options.lang)
    contextOptions.locale = options.lang;

  // Color scheme

View on GitHub (pinned to 9642f57665)

Solutions

Use the exact `username:password` format, quoting the whole flag value: `npx playwright open --http-credentials="admin:secret"`.
For an empty password keep the separator: `--http-credentials="admin:"`.
If building the flag programmatically, validate the env value contains ':' before spawning the CLI (see validationCode) so misconfiguration fails with your own message.

Example fix

# before
npx playwright open --http-credentials=admin https://example.com
# Error: Invalid http credentials format...

# after
npx playwright open --http-credentials="admin:secret" https://example.com

Defensive patterns

Strategy: validation

Validate before calling

// Validate before spawning the CLI
const creds = process.env.BASIC_AUTH; // e.g. "admin:secret"
if (!creds || !creds.includes(':'))
  throw new Error(`BASIC_AUTH must be "username:password", got: ${creds ?? '(unset)'}`);
const args = ['open', `--http-credentials=${creds}`, url];

Prevention

Always quote the whole flag value in shells: --http-credentials="admin:secret".
Keep an empty password explicit with a trailing colon ("admin:").
When credentials come from env vars or secret stores, assert the 'username:password' shape in a startup check, not at CLI spawn time.

When it happens

Trigger: Passing `--http-credentials` without a ':' separator, e.g. `npx playwright open --http-credentials=admin` (password forgotten), `--http-credentials=admin secret` (space splits into two args), or a URL-style value like `--http-credentials=http://admin:secret` only works if a colon exists anywhere, but bare `admin` or `secret123` has none. Any value where `options.httpCredentials.indexOf(':') === -1` triggers it.

Common situations: Forgetting the `username:password` syntax; shell quoting that splits the value at the space so only the username reaches the flag; scripts that interpolate credentials from env vars that are undefined or hold only a username; empty password cases where the user omits the trailing colon.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of microsoft/playwright@9642f57665 (2026-08-21). Data as JSON: /api/errors/024bb0f23b4f98f0. Report an issue: GitHub.