{"record":{"id":"8937145fe1e2e580","repo":"jackwener/OpenCLI","slug":"window-must-be-one-of-foreground-background-r","errorCode":null,"errorMessage":"--window must be one of: foreground, background. Received: \"${String(optionRaw)}\"","messagePattern":"--window must be one of: foreground, background\\. Received: \"(.+?)\"","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli.ts","lineNumber":644,"sourceCode":"  });\n  const targetScope = getBrowserScope(session, profileSelection?.contextId);\n  const resolvedTargetPage = targetPage\n    ? await resolveBrowserTargetInSession(page, targetPage, { scope: targetScope, source: 'explicit' })\n    : await resolveStoredBrowserTarget(page, targetScope);\n  if (resolvedTargetPage) {\n    if (!page.setActivePage) {\n      throw new Error('This browser session does not support explicit tab targeting');\n    }\n    page.setActivePage(resolvedTargetPage);\n  }\n  return page;\n}\n\nfunction getBrowserWindowMode(command: Command | undefined, defaultMode: BrowserWindowMode): BrowserWindowMode {\n  const optionRaw = getCommandOption(command, 'window');\n  if (optionRaw !== undefined && optionRaw !== '') {\n    if (optionRaw === 'foreground' || optionRaw === 'background') return optionRaw;\n    throw new Error(`--window must be one of: foreground, background. Received: \"${String(optionRaw)}\"`);\n  }\n  const envRaw = process.env.OPENCLI_WINDOW;\n  if (envRaw !== undefined && envRaw !== '') {\n    if (envRaw === 'foreground' || envRaw === 'background') return envRaw;\n    throw new Error(`OPENCLI_WINDOW must be one of: foreground, background. Received: \"${envRaw}\"`);\n  }\n  return defaultMode;\n}\n\nfunction addBrowserTabOption(command: Command): Command {\n  return command.option('--tab <targetId>', BROWSER_TAB_OPTION_DESCRIPTION);\n}\n\nfunction getBrowserTargetId(command?: Command): string | undefined {\n  if (!command) return undefined;\n  const opts = command.optsWithGlobals ? command.optsWithGlobals() : command.opts();\n  return typeof opts.tab === 'string' && opts.tab.trim() ? opts.tab.trim() : undefined;\n}","sourceCodeStart":626,"sourceCodeEnd":662,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/cli.ts#L626-L662","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Use exactly foreground or background: opencli browser <session> <command> --window background.","Fix or unset the OPENCLI_WINDOW environment variable if --window isn't passed.","Quote the flag value in shell scripts to avoid the shell mangling it.","Check `opencli browser --help` for accepted values."],"exampleFix":"// before\nexport OPENCLI_WINDOW=minimized\n// after\nexport OPENCLI_WINDOW=background","handlingStrategy":"validation","validationCode":"const WINDOW_MODES = ['foreground', 'background'];\nfunction validateWindowMode(raw) {\n  if (raw !== undefined && raw !== '' && !WINDOW_MODES.includes(raw)) {\n    throw new Error(`--window must be foreground or background, got: ${raw}`);\n  }\n  return raw;\n}","typeGuard":"const isBrowserWindowMode = (v: unknown): v is BrowserWindowMode =>\n  v === 'foreground' || v === 'background';","tryCatchPattern":"try {\n  const mode = getBrowserWindowMode(command, 'foreground');\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('--window must be')) {\n    console.error(err.message, '- defaulting to foreground');\n    return 'foreground';\n  }\n  throw err;\n}","preventionTips":["Only use the literal values foreground/background for --window.","Check and unset a bad OPENCLI_WINDOW env var if --window isn't passed.","Add a CI/shell lint that validates flag values in scripts.","Copy flag syntax from `opencli browser --help`, not other CLIs."],"tags":["cli","validation","arguments","env-var"],"backgroundTag":"invalid-option-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}