jackwener/OpenCLI · error

OPENCLI_WINDOW must be one of: foreground, background. Recei

Error message

OPENCLI_WINDOW must be one of: foreground, background. Received: "${envRaw}"

What it means

opencli resolves the browser window mode from the --window flag or the OPENCLI_WINDOW environment variable. The value must be exactly 'foreground' or 'background'; anything else throws this error at CLI start. It exists to fail fast on a typo'd env var rather than silently falling back to a default window mode.

Source

Thrown at src/cli.ts:649

  if (resolvedTargetPage) {
    if (!page.setActivePage) {
      throw new Error('This browser session does not support explicit tab targeting');
    }
    page.setActivePage(resolvedTargetPage);
  }
  return page;
}

function getBrowserWindowMode(command: Command | undefined, defaultMode: BrowserWindowMode): BrowserWindowMode {
  const optionRaw = getCommandOption(command, 'window');
  if (optionRaw !== undefined && optionRaw !== '') {
    if (optionRaw === 'foreground' || optionRaw === 'background') return optionRaw;
    throw new Error(`--window must be one of: foreground, background. Received: "${String(optionRaw)}"`);
  }
  const envRaw = process.env.OPENCLI_WINDOW;
  if (envRaw !== undefined && envRaw !== '') {
    if (envRaw === 'foreground' || envRaw === 'background') return envRaw;
    throw new Error(`OPENCLI_WINDOW must be one of: foreground, background. Received: "${envRaw}"`);
  }
  return defaultMode;
}

function addBrowserTabOption(command: Command): Command {
  return command.option('--tab <targetId>', BROWSER_TAB_OPTION_DESCRIPTION);
}

function getBrowserTargetId(command?: Command): string | undefined {
  if (!command) return undefined;
  const opts = command.optsWithGlobals ? command.optsWithGlobals() : command.opts();
  return typeof opts.tab === 'string' && opts.tab.trim() ? opts.tab.trim() : undefined;
}

function getCommandOption(command: Command | undefined, option: string): unknown {
  let current: Command | undefined = command;
  while (current) {
    const opts = current.opts();

View on GitHub (pinned to 49907e53dc)

Solutions

1. Unset OPENCLI_WINDOW (unset OPENCLI_WINDOW) to fall back to the default mode
2. Set it to exactly 'foreground' or 'background': export OPENCLI_WINDOW=background
3. Check for stray whitespace or casing: printf '%q\n' "$OPENCLI_WINDOW"; the comparison is case-sensitive
4. Pass the --window flag instead, which overrides or replaces the env var

Example fix

// before
export OPENCLI_WINDOW=Foreground
// after
export OPENCLI_WINDOW=foreground

const mode = process.env.OPENCLI_WINDOW;
if (mode !== undefined && mode !== '' && mode !== 'foreground' && mode !== 'background') {
  throw new Error(`OPENCLI_WINDOW must be 'foreground' or 'background', got: ${JSON.stringify(mode)}`);
}

function isValidWindowMode(v: unknown): v is 'foreground' | 'background' {
  return v === 'foreground' || v === 'background';
}

When it happens

Trigger: OPENCLI_WINDOW is set to any value other than 'foreground' or 'background' (case-sensitive, no trimming), e.g. OPENCLI_WINDOW=Foreground, FOREGROUND, front, or ' foreground '.

Common situations: CI/container env files exporting OPENCLI_WINDOW with a typo or wrong casing; shell scripts exporting an empty-adjacent value; users assuming boolean or numeric values are accepted.

Related errors

• --window must be one of: foreground, background. Received: "
• ${label} is required
• ${label} must be a positive integer
• ${label} must be <= ${maxValue}
• ${label} must be a numeric ID

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/851b2bff6575b7f0. Report an issue: GitHub.