What causes "Invalid color scheme, should be one of "light", "dark"" in microsoft/playwright?

Pass exactly 'light' or 'dark': `npx playwright open --color-scheme=dark https://example.com`.

microsoft/playwright · error · Error

Invalid color scheme, should be one of "light", "dark"

Error message

Invalid color scheme, should be one of "light", "dark"

What it means

Thrown by validateOptions() in the `playwright open` / `playwright pdf` CLI when the --color-scheme flag receives a value other than 'light' or 'dark'. The CLI option is parsed freely as a string, so this guard rejects unsupported values before launching a browser context. It mirrors the public API contract where colorScheme is typed as 'light'|'dark'|'no-preference'.

Source

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

    case 'firefox': browserType = playwright.firefox; break;
    case 'cr': browserType = playwright.chromium; break;
    case 'wk': browserType = playwright.webkit; break;
    case 'ff': browserType = playwright.firefox; break;
  }
  if (browserType)
    return browserType;
  program.help();
}

function validateOptions(options: Options) {
  if (options.device && !(options.device in playwright.devices)) {
    const lines = [`Device descriptor not found: '${options.device}', available devices are:`];
    for (const name in playwright.devices)
      lines.push(`  "${name}"`);
    throw new Error(lines.join('\n'));
  }
  if (options.colorScheme && !['light', 'dark'].includes(options.colorScheme))
    throw new Error('Invalid color scheme, should be one of "light", "dark"');
}

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Pass exactly 'light' or 'dark': `npx playwright open --color-scheme=dark https://example.com`.
Omit --color-scheme entirely to use the default.
Check for stray whitespace or copy-paste artifacts in the flag value.

Example fix

// before
npx playwright open --color-scheme=blue https://example.com
// after
npx playwright open --color-scheme=dark https://example.com

Defensive patterns

Strategy: validation

Validate before calling

const scheme = process.env.PW_COLOR_SCHEME;
if (scheme && !['light', 'dark'].includes(scheme))
  throw new Error(`Unsupported --color-scheme '${scheme}'`);
// then pass scheme to the CLI or use options programmatically

Type guard

function isValidColorScheme(v: string): v is 'light' | 'dark' {
  return v === 'light' || v === 'dark';
}

Prevention

Restrict the CLI flag value with an enum in any wrapper script.
Document that only 'light' and 'dark' are accepted (no 'auto'/'system').

When it happens

Trigger: Running `npx playwright open --color-scheme=blue url`, `npx open --color-scheme dark-blue`, or any CLI invocation that passes a colorScheme value not in the ['light','dark'] whitelist. The check fires only when options.colorScheme is truthy and not included in the array.

Common situations: Typing a custom hex color name, passing 'auto' or 'system', or quoting a value with extra whitespace. Developers sometimes assume the CLI accepts the same values as CSS prefers-color-scheme.

Related errors

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