{"record":{"id":"6783fd4b3836fb77","repo":"jackwener/OpenCLI","slug":"argument-argdef-name-must-be-a-boolean-true","errorCode":null,"errorMessage":"Argument \"${argDef.name}\" must be a boolean (true/false). Received: \"${val}\"","messagePattern":"Argument \"(.+?)\" must be a boolean \\(true/false\\)\\. Received: \"(.+?)\"","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"src/execution.ts","lineNumber":82,"sourceCode":"      );\n    }\n\n    if (val !== undefined && val !== null) {\n      if (argDef.type === 'int' || argDef.type === 'number') {\n        const num = Number(val);\n        if (!Number.isFinite(num)) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be a valid number. Received: \"${val}\"`);\n        }\n        if (argDef.type === 'int' && !Number.isInteger(num)) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be a valid integer. Received: \"${val}\"`);\n        }\n        result[argDef.name] = num;\n      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {\n        if (typeof val === 'string') {\n          const lower = val.toLowerCase();\n          if (lower === 'true' || lower === '1') result[argDef.name] = true;\n          else if (lower === 'false' || lower === '0') result[argDef.name] = false;\n          else throw new ArgumentError(`Argument \"${argDef.name}\" must be a boolean (true/false). Received: \"${val}\"`);\n        } else {\n          result[argDef.name] = Boolean(val);\n        }\n      }\n\n      const coercedVal = result[argDef.name];\n      if (argDef.choices && argDef.choices.length > 0) {\n        if (!argDef.choices.map(String).includes(String(coercedVal))) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be one of: ${argDef.choices.join(', ')}. Received: \"${coercedVal}\"`);\n        }\n      }\n    } else if (argDef.default !== undefined) {\n      result[argDef.name] = argDef.default;\n    }\n  }\n  return result;\n}\n","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/execution.ts#L64-L100","documentation":"For arguments typed 'boolean'/'bool', coerceAndValidateArgs accepts true/false (case-insensitive) and '1'/'0' strings; numeric/other types are coerced with Boolean(). A string that is not one of true/false/1/0 (case-insensitive) throws ArgumentError requiring a boolean value.","triggerScenarios":"Passing --headless yes, --debug on, --enabled TRUE-ish variants outside the accepted set (e.g. 'y', 't'), or kwargs like { dryRun: 'maybe' } to a bool-typed argument.","commonSituations":"Shell conventions using yes/no or on/off; interactive prompts feeding 'Y'/'N'; config files with boolean-like strings other than the accepted four.","solutions":["Use true/false (or 1/0), e.g. --headless true.","Map yes/no or on/off to true/false in the calling script before passing.","In programmatic use, pass actual booleans rather than strings.","Check the argument's declared type; if it should accept more forms, update the arg definition (library-side)."],"exampleFix":"// before\nopencli run --headless yes\n// after\nopencli run --headless true","handlingStrategy":"validation","validationCode":"function toBool(v: unknown): boolean {\n  if (typeof v === 'boolean') return v;\n  const s = String(v).toLowerCase();\n  if (s === 'true' || s === '1') return true;\n  if (s === 'false' || s === '0') return false;\n  throw new Error(`Expected boolean (true/false/1/0), got: ${String(v)}`);\n}\nkwargs.headless = toBool(kwargs.headless);","typeGuard":"const isBooleanLike = (v: unknown): v is boolean | 'true' | 'false' | '1' | '0' =>\n  typeof v === 'boolean' || ['true', 'false', '1', '0'].includes(String(v).toLowerCase());","tryCatchPattern":"try {\n  await opencli.run(cmd, kwargs);\n} catch (e) {\n  if (/must be a boolean/.test(e.message)) {\n    console.error(`${e.message} — map yes/no or on/off to true/false first.`);\n  } else throw e;\n}","preventionTips":["Use true/false (or 1/0) instead of yes/no, on/off, Y/N.","Pass real booleans, not strings, in programmatic kwargs.","Normalize boolean-like input at the script boundary before invoking the CLI."],"tags":["cli","type-coercion","boolean"],"backgroundTag":"invalid-boolean-argument","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}