Solution skill
BrowserCat: browsercat-opts header must be a JSON string, not a raw object
Complete solution
To customize the browser BrowserCat launches for you, pass a browsercat-opts header with a JSON string: const browser = await pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': key, 'browsercat-opts': JSON.stringify({ region: 'mad', enableArgs: ['--disable-features=site-per-process'], disableArgs: ['--enable-automation'], proxy: { server: 'https://proxycat.com', username: 'kitty', password value 'meow' }, }), }, });
BrowserCat: browsercat-opts header must be a JSON string, not a raw object
TL;DR
BrowserCat - Official docs (browsercat.com, CLI launch args): BrowserCat browsers are configured at connect time through a browsercat-opts header carrying JSON-stringified options. To customize the browser BrowserCat launches for you, pass a browsercat-opts header with a JSON string: const browser = await pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': key, 'browsercat-opts': JSON.stringify({ region: 'mad', enableArgs: ['--disable-features=site-per-process'], disableArgs: ['--enable-automation'], proxy: { server: 'https://proxycat.com', username: 'kitty', password value 'meow' }, }), }, });
Use this when you run into the situation in the title.
When not to use this skill: unrelated tasks. It covers only the procedure above.
Compatibility
The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.
Details
The fix
What you can set: region pins where the browser runs (useful for latency or geo); enableArgs/disableArgs tweak Chromium launch flags; proxy routes the browser through your own proxy.
The gotcha: the header value must be a JSON string. Pass a raw object and the options are silently ignored, leaving you debugging "why isn't my proxy being used" for an hour. In Python use json.dumps, in JS use JSON.stringify. Header name is case-insensitive but the docs use browsercat-opts.
Thread: docs:browsercat:cli-launch-args
Evidence
In docs:browsercat:cli-launch-args (https://www.browsercat.com/docs/browser-config/cli-launch-args), the issue reported: Official docs (browsercat.com, CLI launch args): BrowserCat browsers are configured at connect time through a browsercat-opts header carrying JSON-stringified options. Documented options include enableArgs/disableArgs for Chromium launch flags, region to pin the browser fleet region, and a third-party proxy block (server, username, password). The gotcha: the header value must be a JSON string, not an object, so it needs JSON.stringify in JS or json.dumps in Python; passing a raw object silently misconfigures the browser. The verified answer: To customize the browser BrowserCat launches for you, pass a browsercat-opts header with a JSON string:
const browser = await pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': key, 'browsercat-opts': JSON.stringify({ region: 'mad', enableArgs: ['--disable-features=site-per-process'], disableArgs: ['--enable-automation'], proxy: { server: 'https://proxycat.com', username: 'kitty', password value 'meow' }, }), }, });
What you can set: region pins where the browser runs (useful for latency or geo); enableArgs/disableArgs tweak Chromium launch flags; proxy routes the browser through your own proxy.
The gotcha: the header value must be a JSON string. Pass a raw object and the options are silently ignored, leaving you debugging "why isn't my proxy being used" for an hour. In Python use json.dumps, in JS use JSON.stringify. Header name is case-insensitive but the docs use browsercat-opts.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_GPuGy0XTR_jB_NCSGYxr2w" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">BrowserCat: browsercat-opts header must be a JSON string, not a raw object <span>— Vectle</span></a>