microsoft/playwright · error · Error

boolean option '--${key}' should not be passed with '=value'

Error message

boolean option '--${key}' should not be passed with '=value', use '--${key}' or '--no-${key}' instead

What it means

Thrown by the minimist-based CLI arg parser when an argument of the form --key=value is parsed and key is registered as a boolean option. Boolean options must be passed as --key (true) or --no-key (false); attaching an =value is ambiguous and rejected.

Source

Thrown at packages/playwright-core/src/tools/cli-client/minimist.ts:76

  }

  let notFlags: string[] = [];
  const doubleDashIndex = args.indexOf('--');
  if (doubleDashIndex !== -1) {
    notFlags = args.slice(doubleDashIndex + 1);
    args = args.slice(0, doubleDashIndex);
  }

  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    let key: string;
    let next: string;

    if ((/^--.+=/).test(arg)) {
      const m = arg.match(/^--([^=]+)=([\s\S]*)$/)!;
      key = m[1];
      if (bools[key])
        throw new Error(`boolean option '--${key}' should not be passed with '=value', use '--${key}' or '--no-${key}' instead`);
      setArg(key, m[2]);
    } else if ((/^--no-.+/).test(arg)) {
      key = arg.match(/^--no-(.+)/)![1];
      setArg(key, false);
    } else if ((/^--.+/).test(arg)) {
      key = arg.match(/^--(.+)/)![1];
      next = args[i + 1];
      if (
        next !== undefined
        && !(/^(-|--)[^-]/).test(next)
        && !bools[key]
      ) {
        setArg(key, next);
        i += 1;
      } else if ((/^(true|false)$/).test(next)) {
        setArg(key, next === 'true');
        i += 1;
      } else {

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Pass boolean flags bare: --headless (or its inverse --no-headless).
2. For string/number options, =value or a separate token both work — only booleans reject =value.
3. Audit your command template and convert boolean flags away from the = form.

Example fix

# before
playwright-cli open --headless=true   # throws

# after
playwright-cli open --headless
# or
playwright-cli open --no-headless

function normalizeCliArgs(argv: string[], bools: Record<string, boolean>): string[] {
  return argv.map(a => {
    const m = a.match(/^--([^=]+)=(.+)$/);
    if (m && bools[m[1]]) {
      return m[2] === 'false' ? `--no-${m[1]}` : `--${m[1]}`;
    }
    return a;
  });
}

function isBooleanFlagForm(arg: string, bools: Record<string, boolean>): boolean {
  const m = arg.match(/^--([^=]+)=/);
  return !!m && !!bools[m[1]];
}

// Prefer normalizing the args before invoking the parser; try/catch is awkward here
// because the parser runs before your code. Use the normalizeCliArgs helper above.

When it happens

Trigger: Running the playwright CLI (or any tool built on this minimist wrapper) with e.g. --headless=true or --no-sandbox=false where the option is declared boolean.

Common situations: User habitually appending =true to boolean flags; copied flags from a shell snippet that mixed boolean and string styles; CI config that normalizes all flags to --x=y form.

Related errors

• error: too many arguments: expected ${argNames.length}, rece
• --data must be in "mime/type=value" format, got: ${entry}
• Command is required
• Invalid viewport size format: use "width,height", for exampl
• Invalid geolocation format, should be "lat,long". For exampl

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