[cloakbrowser] contextOptions.timezoneId ignored — use top-l

Error message

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

What it means

A console.warn telling you that contextOptions.timezoneId is ignored. Timezone is applied via a Chromium binary flag at launch, since Playwright's per-context CDP timezone emulation leaks detectable signals. Pass timezone as a top-level launch option instead.

Source

Thrown at js/src/playwright.ts:52

  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
 * keeping the wrapper's stealth-safe defaults for `newContext()`.
 */
/**
 * Effective headless mode for viewport decisions. buildLaunchOptions() spreads
 * `...options.launchOptions` LAST, so a raw `launchOptions.headless` overrides the
 * top-level field at the actual chromium.launch() call. Viewport logic must read

View on GitHub (pinned to d6bad5de26)

Solutions

Move the setting to top-level: { timezone: 'Europe/Paris' } (note the renamed key, not timezoneId).
Drop timezoneId from contextOptions to silence the warning.

Example fix

// before
await cloakbrowser.launchPersistentContext(dir, {
  contextOptions: { timezoneId: 'Europe/Paris' }
});

// after
await cloakbrowser.launchPersistentContext(dir, {
  timezone: 'Europe/Paris'
});

Defensive patterns

Strategy: validation

Validate before calling

if (opts?.contextOptions?.timezoneId !== undefined) {
  throw new Error('use top-level `timezone` option; contextOptions.timezoneId is ignored');
}

Type guard

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

Prevention

Remember the renamed key: top-level is `timezone`, not `timezoneId`.
Set locale/timezone once in a shared launch config so per-context copies don't reappear.

When it happens

Trigger: Calling launch/launchPersistentContext with { contextOptions: { timezoneId: 'Europe/Paris' } }. The key is stripped from the merged context options and the warning is emitted.

Common situations: Migrating Playwright scripts that used browser.newContext({ timezoneId }); observing pages render in the system timezone despite the setting.

Related errors

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