microsoft/playwright · error · Error

error: '--params' option: expected a JSON object, received

Error message

error: '--params' option: expected a JSON object, received '${params}'

What it means

The CLI daemon's --params option must parse to a JSON object. This throw site handles JSON.parse failures: the provided string is not syntactically valid JSON, so the command aborts with a formatted error. The helper returns undefined when --params is absent, so this only fires when a value was supplied.

Solutions

Quote the whole value in single quotes in POSIX shells: --params '{"tool":"x","input":"{}"}'.
Validate the string with JSON.parse (e.g. node -e "JSON.parse(process.argv[1])") before passing it.
Avoid --params entirely if no parameters are needed (it is optional).

Example fix

// before (shell strips quotes)
webmcp-call --params {"name":"get-weather"}
// after
webmcp-call --params '{"name":"get-weather"}'

Defensive patterns

Strategy: validation

Validate before calling

function isJsonObjectString(s) {
  if (s === undefined) return true;
  try { const v = JSON.parse(s); return typeof v === 'object' && v !== null && !Array.isArray(v); } catch { return false; }
}
// assert before invoking the CLI

Try / catch

try {
  await runCli(['webmcp-call', '--params', paramsStr]);
} catch (e) {
  if (e.message.includes("'--params' option")) throw new Error(`Bad --params: ${paramsStr}. Use single-quoted strict JSON object.`);
  throw e;
}

Prevention

Always single-quote --params values in POSIX shells.
Use JSON.stringify(obj) in scripts instead of hand-written JSON.
Validate with JSON.parse before invoking the CLI.

When it happens

Trigger: Passing --params with malformed JSON, e.g. --params "{tool:'x'}" (single quotes / unquoted keys) or unescaped quotes in the shell that get stripped before parsing.

Common situations: Shell quoting stripping double quotes (--params {"tool":"x"} becomes {tool:x}); writing JS object literals instead of JSON; Windows cmd quoting differences.

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@f1d33b5029 (2026-09-15). Data as JSON: /api/errors/d4d235fe237fa1d2. Report an issue: GitHub.

Appendix: source

Thrown at packages/playwright-core/src/tools/cli-daemon/commands.ts:1283

const tray = declareCommand({
  name: 'tray',
  description: 'Run tray',
  category: 'config',
  hidden: true,
  toolName: '',
  toolParams: () => ({}),
});

// WebMCP

function parseWebMCPParams(params: string | undefined) {
  if (params === undefined)
    return undefined;
  let parsed: unknown;
  try {
    parsed = JSON.parse(params);
  } catch (e) {
    throw new Error(`error: '--params' option: expected a JSON object, received '${params}'`);
  }
  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
    throw new Error(`error: '--params' option: expected a JSON object, received '${params}'`);
  return parsed as Record<string, unknown>;
}

const webmcpList = declareCommand({
  name: 'webmcp-list',
  description: 'List the WebMCP tools registered by the page',
  category: 'webmcp',
  args: z.object({}),
  toolName: 'browser_webmcp_list',
  toolParams: () => ({}),
});

const webmcpCall = declareCommand({
  name: 'webmcp-call',
  description: 'Call a WebMCP tool registered by the page',

View on GitHub (pinned to f1d33b5029)