{"record":{"id":"ed71d21da8a52f04","repo":"CloakHQ/CloakBrowser","slug":"cloakbrowser-contextoptions-locale-ignored-use","errorCode":null,"errorMessage":"[cloakbrowser] contextOptions.locale ignored — use top-level `locale` instead (routes through binary flag, avoids detectable CDP emulation).","messagePattern":"\\[cloakbrowser\\] contextOptions\\.locale ignored — use top-level `locale` instead \\(routes through binary flag, avoids detectable CDP emulation\\)\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"js/src/playwright.ts","lineNumber":46,"sourceCode":"export function resolveTimezone<T extends { timezone?: string; timezoneId?: string }>(options: T): T {\n  if (options.timezoneId != null) {\n    const merged = { ...options, timezone: options.timezone ?? options.timezoneId };\n    delete (merged as any).timezoneId;\n    return merged;\n  }\n  return options;\n}\n\n/**\n * Strip `locale` and `timezoneId` from user-provided contextOptions — both route\n * through detectable CDP emulation. The wrapper's top-level `locale`/`timezone`\n * fields use binary flags instead (undetectable). Warn so users notice.\n */\nfunction filterStealthCtxOptions(ctx?: BrowserContextOptions): Partial<BrowserContextOptions> {\n  if (!ctx) return {};\n  const { locale, timezoneId, ...rest } = ctx;\n  if (locale !== undefined) {\n    console.warn(\n      \"[cloakbrowser] contextOptions.locale ignored — use top-level `locale` \" +\n      \"instead (routes through binary flag, avoids detectable CDP emulation).\"\n    );\n  }\n  if (timezoneId !== undefined) {\n    console.warn(\n      \"[cloakbrowser] contextOptions.timezoneId ignored — use top-level `timezone` \" +\n      \"instead (routes through binary flag, avoids detectable CDP emulation).\"\n    );\n  }\n  return rest;\n}\n\n/**\n * Build Playwright BrowserContext options for CloakBrowser without launching a browser\n * or creating a context.\n *\n * Useful when integrating CloakBrowser with an existing Playwright Browser while","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/CloakHQ/CloakBrowser/blob/d6bad5de261bedf025280ace1d14e800aee13923/js/src/playwright.ts#L28-L64","documentation":"A console.warn telling you that the locale field inside contextOptions is intentionally ignored. CloakBrowser routes locale through a Chromium binary flag (--lang) at launch time because setting locale via Playwright's CDP emulation is detectable by anti-bot systems. You must pass locale as a top-level launch option instead of inside contextOptions.","triggerScenarios":"Calling launch/launchPersistentContext with options like { contextOptions: { locale: 'fr-FR' } }. The field is destructured out and discarded, and this warning is printed.","commonSituations":"Porting existing Playwright/Puppeteer scripts that set browser.newContext({ locale }) and finding the locale silently not applied; assuming contextOptions passes through verbatim.","solutions":["Move locale out of contextOptions to the top-level options: { locale: 'fr-FR' }.","Remove the locale key from contextOptions to silence the warning entirely."],"exampleFix":"// before\nawait cloakbrowser.launchPersistentContext(dir, {\n  contextOptions: { locale: 'fr-FR' }\n});\n\n// after\nawait cloakbrowser.launchPersistentContext(dir, {\n  locale: 'fr-FR'\n});","handlingStrategy":"validation","validationCode":"// reject deprecated context-level locale before launch\nfunction assertNoCtxLocale(opts: any): void {\n  if (opts?.contextOptions?.locale !== undefined) {\n    throw new Error('move locale to top-level options (contextOptions.locale is ignored)');\n  }\n}\nassertNoCtxLocale(launchOpts);","typeGuard":"const hasIgnoredLocale = (o: unknown): boolean =>\n  !!o && typeof o === 'object' && 'locale' in (o as any).contextOptions;","tryCatchPattern":null,"preventionTips":["Keep a single typed launch-options object where locale lives at the top level only.","Lint for contextOptions.locale/timezoneId in code review when migrating Playwright scripts."],"tags":["locale","playwright","stealth","configuration"],"backgroundTag":"deprecated-option-ignored","analyzedSha":"d6bad5de261bedf025280ace1d14e800aee13923","analyzedAt":"2026-08-28T14:13:12.918Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}