{"record":{"id":"fe9f96c4094dd745","repo":"jackwener/OpenCLI","slug":"trace-must-be-one-of-off-on-retain-on-failure","errorCode":null,"errorMessage":"--trace must be one of: off, on, retain-on-failure. Received: \"${String(raw)}\"","messagePattern":"--trace must be one of: off, on, retain-on-failure\\. Received: \"(.+?)\"","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"src/execution.ts","lineNumber":51,"sourceCode":"import { clearDaemonRunContext, generateRunId, isUnknownOutcomeError, releaseSiteSessionLease, setDaemonCommandTimeoutSeconds, setDaemonRunContext } from './browser/daemon-client.js';\nimport { emitHook, type HookContext } from './hooks.js';\nimport { log } from './logger.js';\nimport { isElectronApp } from './electron-apps.js';\nimport { probeCDP, resolveElectronEndpoint } from './launcher.js';\nimport { ObservationSession, exportObservationSession, type ObservationExportResult, type ObservationExportStatus } from './observation/index.js';\nimport { resolveAdapterSourcePath } from './adapter-source.js';\n\nconst _loadedModules = new Map<string, Promise<void>>();\n/** Track mtime of loaded user adapter files for hot-reload in daemon mode. */\nconst _moduleMtimes = new Map<string, number>();\nconst _userClisDir = `${os.homedir()}/.opencli/clis/`;\n\ntype TraceMode = 'off' | 'on' | 'retain-on-failure';\n\nfunction normalizeTraceMode(raw: unknown): TraceMode {\n  if (raw === undefined || raw === null || raw === '' || raw === 'off') return 'off';\n  if (raw === 'on' || raw === 'retain-on-failure') return raw;\n  throw new ArgumentError(`--trace must be one of: off, on, retain-on-failure. Received: \"${String(raw)}\"`);\n}\n\nexport function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {\n  const result: CommandArgs = { ...kwargs };\n\n  for (const argDef of cmdArgs) {\n    const val = result[argDef.name];\n\n    if (argDef.required && (val === undefined || val === null || val === '')) {\n      throw new ArgumentError(\n        `Argument \"${argDef.name}\" is required.`,\n        argDef.help ?? `Provide a value for --${argDef.name}`,\n      );\n    }\n\n    if (val !== undefined && val !== null) {\n      if (argDef.type === 'int' || argDef.type === 'number') {\n        const num = Number(val);","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/execution.ts#L33-L69","documentation":"normalizeTraceMode validates the --trace option, allowing only 'off', 'on', or 'retain-on-failure' (empty/undefined maps to 'off'). Any other value raises an ArgumentError naming the accepted values and the offending input. Playwright-style trace collection is therefore strictly enum-validated before execution.","triggerScenarios":"Passing --trace true, --trace always, --trace retain, --trace ON (case-sensitive), or --trace 1 through kwargs or CLI flags.","commonSituations":"Copy-pasting trace flags from other tools (e.g. Playwright's `retain-on-failure` misspelled as retainonfailure); booleans used where an enum string is expected; case-mismatch after editing config files.","solutions":["Use exactly one of: off, on, retain-on-failure (lowercase).","Omit --trace to default to off.","Fix config/CI files that interpolate a non-enum value into the trace option."],"exampleFix":"// before\n{ trace: 'always' }\n// after\n{ trace: 'retain-on-failure' }","handlingStrategy":"validation","validationCode":"const TRACE_MODES = ['off', 'on', 'retain-on-failure'] as const;\nif (opts.trace !== undefined && !TRACE_MODES.includes(opts.trace as any)) {\n  throw new Error(`--trace must be one of: ${TRACE_MODES.join(', ')}`);\n}","typeGuard":"type TraceMode = 'off' | 'on' | 'retain-on-failure';\nconst isTraceMode = (v: unknown): v is TraceMode =>\n  v === 'off' || v === 'on' || v === 'retain-on-failure';","tryCatchPattern":"try {\n  await opencli.run(cmd, { trace: opts.trace });\n} catch (e) {\n  if (/--trace must be one of/.test(e.message)) {\n    console.error('Use --trace off | on | retain-on-failure');\n  } else throw e;\n}","preventionTips":["Use the exact lowercase enum strings; never true/false or always.","Omit the flag when you don't need traces (defaults to off).","Centralize the trace value in one config constant validated once."],"tags":["cli","argument-validation","trace"],"backgroundTag":"invalid-argument-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}