[cloakbrowser] contextOptions.locale ignored — use top-level

Error message

[cloakbrowser] contextOptions.locale ignored — use top-level `locale` instead (routes through binary flag, avoids detectable CDP emulation).

What it means

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.

Source

Thrown at js/src/playwright.ts:46

export function resolveTimezone<T extends { timezone?: string; timezoneId?: string }>(options: T): T {
  if (options.timezoneId != null) {
    const merged = { ...options, timezone: options.timezone ?? options.timezoneId };
    delete (merged as any).timezoneId;
    return merged;
  }
  return options;
}

/**
 * Strip `locale` and `timezoneId` from user-provided contextOptions — both route
 * through detectable CDP emulation. The wrapper's top-level `locale`/`timezone`
 * fields use binary flags instead (undetectable). Warn so users notice.
 */
function filterStealthCtxOptions(ctx?: BrowserContextOptions): Partial<BrowserContextOptions> {
  if (!ctx) return {};
  const { locale, timezoneId, ...rest } = ctx;
  if (locale !== undefined) {
    console.warn(
      "[cloakbrowser] contextOptions.locale ignored — use top-level `locale` " +
      "instead (routes through binary flag, avoids detectable CDP emulation)."
    );
  }
  if (timezoneId !== undefined) {
    console.warn(
      "[cloakbrowser] contextOptions.timezoneId ignored — use top-level `timezone` " +
      "instead (routes through binary flag, avoids detectable CDP emulation)."
    );
  }
  return rest;
}

/**
 * Build Playwright BrowserContext options for CloakBrowser without launching a browser
 * or creating a context.
 *
 * Useful when integrating CloakBrowser with an existing Playwright Browser while

View on GitHub (pinned to d6bad5de26)

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.

Example fix

// before
await cloakbrowser.launchPersistentContext(dir, {
  contextOptions: { locale: 'fr-FR' }
});

// after
await cloakbrowser.launchPersistentContext(dir, {
  locale: 'fr-FR'
});

Defensive patterns

Strategy: validation

Validate before calling

// reject deprecated context-level locale before launch
function assertNoCtxLocale(opts: any): void {
  if (opts?.contextOptions?.locale !== undefined) {
    throw new Error('move locale to top-level options (contextOptions.locale is ignored)');
  }
}
assertNoCtxLocale(launchOpts);

Type guard

const hasIgnoredLocale = (o: unknown): boolean =>
  !!o && typeof o === 'object' && 'locale' in (o as any).contextOptions;

Prevention

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.

When it happens

Trigger: Calling launch/launchPersistentContext with options like { contextOptions: { locale: 'fr-FR' } }. The field is destructured out and discarded, and this warning is printed.

Common situations: Porting existing Playwright/Puppeteer scripts that set browser.newContext({ locale }) and finding the locale silently not applied; assuming contextOptions passes through verbatim.

Related errors

AI-assisted analysis of CloakHQ/CloakBrowser@d6bad5de26 (2026-08-28). Data as JSON: /api/errors/ed71d21da8a52f04. Report an issue: GitHub.