{"record":{"id":"851b2bff6575b7f0","repo":"jackwener/OpenCLI","slug":"opencli-window-must-be-one-of-foreground-backgro","errorCode":null,"errorMessage":"OPENCLI_WINDOW must be one of: foreground, background. Received: \"${envRaw}\"","messagePattern":"OPENCLI_WINDOW must be one of: foreground, background\\. Received: \"(.+?)\"","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli.ts","lineNumber":649,"sourceCode":"  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}\n\nfunction getCommandOption(command: Command | undefined, option: string): unknown {\n  let current: Command | undefined = command;\n  while (current) {\n    const opts = current.opts();","sourceCodeStart":631,"sourceCodeEnd":667,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/cli.ts#L631-L667","documentation":"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.","triggerScenarios":"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 '.","commonSituations":"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.","solutions":["Unset OPENCLI_WINDOW (unset OPENCLI_WINDOW) to fall back to the default mode","Set it to exactly 'foreground' or 'background': export OPENCLI_WINDOW=background","Check for stray whitespace or casing: printf '%q\\n' \"$OPENCLI_WINDOW\"; the comparison is case-sensitive","Pass the --window flag instead, which overrides or replaces the env var"],"exampleFix":"// before\nexport OPENCLI_WINDOW=Foreground\n// after\nexport OPENCLI_WINDOW=foreground","handlingStrategy":"validation","validationCode":"const mode = process.env.OPENCLI_WINDOW;\nif (mode !== undefined && mode !== '' && mode !== 'foreground' && mode !== 'background') {\n  throw new Error(`OPENCLI_WINDOW must be 'foreground' or 'background', got: ${JSON.stringify(mode)}`);\n}","typeGuard":"function isValidWindowMode(v: unknown): v is 'foreground' | 'background' {\n  return v === 'foreground' || v === 'background';\n}","tryCatchPattern":null,"preventionTips":["Set OPENCLI_WINDOW in only one canonical place (e.g. .env / CI config) and review casing","Validate env vars at script startup with a small allowlist check","Avoid surrounding whitespace: export OPENCLI_WINDOW=background (no quotes with spaces)","Prefer the --window flag in scripts so behavior doesn't depend on ambient env"],"tags":["env-var","cli","validation"],"backgroundTag":"invalid-env-var-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}