jackwener/OpenCLI · error

--window must be one of: foreground, background. Received: "

Error message

--window must be one of: foreground, background. Received: "${String(optionRaw)}"

What it means

getBrowserWindowMode reads the --window option (falling back to OPENCLI_WINDOW env) and only accepts 'foreground' or 'background'. Any other non-empty value for the flag throws immediately, listing the allowed values and the received value, so invalid window modes are rejected before launching a browser.

Source

Thrown at src/cli.ts:644

  });
  const targetScope = getBrowserScope(session, profileSelection?.contextId);
  const resolvedTargetPage = targetPage
    ? await resolveBrowserTargetInSession(page, targetPage, { scope: targetScope, source: 'explicit' })
    : await resolveStoredBrowserTarget(page, targetScope);
  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;
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Use exactly foreground or background: opencli browser <session> <command> --window background.
2. Fix or unset the OPENCLI_WINDOW environment variable if --window isn't passed.
3. Quote the flag value in shell scripts to avoid the shell mangling it.
4. Check `opencli browser --help` for accepted values.

Example fix

// before
export OPENCLI_WINDOW=minimized
// after
export OPENCLI_WINDOW=background

const WINDOW_MODES = ['foreground', 'background'];
function validateWindowMode(raw) {
  if (raw !== undefined && raw !== '' && !WINDOW_MODES.includes(raw)) {
    throw new Error(`--window must be foreground or background, got: ${raw}`);
  }
  return raw;
}

const isBrowserWindowMode = (v: unknown): v is BrowserWindowMode =>
  v === 'foreground' || v === 'background';

try {
  const mode = getBrowserWindowMode(command, 'foreground');
} catch (err) {
  if (err instanceof Error && err.message.startsWith('--window must be')) {
    console.error(err.message, '- defaulting to foreground');
    return 'foreground';
  }
  throw err;
}

When it happens

Trigger: Running a browser command with --window=visible, --window front, or any value other than foreground/background; also setting OPENCLI_WINDOW to an invalid value when --window is absent.

Common situations: Typos or synonyms from other tools (--window=minimized); copy-pasting flags from a different CLI; exporting OPENCLI_WINDOW globally with a wrong value so all browser commands fail; empty-vs-set confusion (empty string falls through to env).

Understand the failure class

Background: Invalid option value errors: "must be one of", "is not a valid", and "only allows" failures explained — this error's family across 23 libraries.

Related errors

• ${label} is required
• ${label} must be a positive integer
• ${label} must be <= ${maxValue}
• dblp ${label} must be a positive integer
• dblp ${label} must be <= ${maxValue}

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