{"record":{"id":"a6f37350b3d643af","repo":"can1357/oh-my-pi","slug":"error-instanceof-error-error-message-string-er-a6f373","errorCode":null,"errorMessage":"error instanceof Error ? error.message : String(error)","messagePattern":"error instanceof Error \\? error\\.message : String\\(error\\)","errorType":"exception","errorClass":"CliUsageError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/cli.ts","lineNumber":219,"sourceCode":"\t\t\tif (desc.multiple) opt.multiple = true;\n\t\t\tif (desc.default !== undefined) {\n\t\t\t\topt.default = desc.kind === \"boolean\" ? Boolean(desc.default) : String(desc.default);\n\t\t\t}\n\t\t\toptions[name] = opt;\n\t\t}\n\n\t\t// strict=false when command declares args (positionals must pass through)\n\t\t// or when the command itself opts out\n\t\tconst { values: rawValues, positionals } = (() => {\n\t\t\ttry {\n\t\t\t\treturn nodeParseArgs({\n\t\t\t\t\targs: this.argv,\n\t\t\t\t\toptions,\n\t\t\t\t\tallowPositionals: true,\n\t\t\t\t\tstrict,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tthrow new CliUsageError(error instanceof Error ? error.message : String(error));\n\t\t\t}\n\t\t})();\n\n\t\t// Convert raw values to proper types and validate\n\t\tconst flags: Record<string, unknown> = {};\n\t\tfor (const [name, desc] of Object.entries(flagDefs)) {\n\t\t\tconst raw = rawValues[name];\n\t\t\tif (desc.kind === \"integer\") {\n\t\t\t\tif (raw === undefined || typeof raw === \"boolean\") {\n\t\t\t\t\tflags[name] = desc.default ?? undefined;\n\t\t\t\t} else {\n\t\t\t\t\tconst n = Number.parseInt(raw as string, 10);\n\t\t\t\t\tif (Number.isNaN(n)) {\n\t\t\t\t\t\tthrow new CliUsageError(`Expected integer for --${name}, got \"${raw}\"`);\n\t\t\t\t\t}\n\t\t\t\t\tflags[name] = n;\n\t\t\t\t}\n\t\t\t} else if (desc.kind === \"boolean\") {","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/cli.ts#L201-L237","documentation":"parse() wraps failures from Node's util.parseArgs (invalid option syntax, unknown flags in strict mode, unexpected positional values) into a CliUsageError whose message is the underlying parser message. It signals the command line itself was malformed, not that the program failed at runtime.","triggerScenarios":"Calling cli.parse() with an unknown flag in strict mode, a flag given without its required value, an option value where a boolean was declared, or a positional in a spot that conflicts with the declared args.","commonSituations":"Users typo a flag (--verbos instead of --verbose), pass `--flag=value` where the grammar expects space-separated values, or scripts pass stale flags after the CLI surface changed between versions.","solutions":["Fix the offending flag/value per the wrapped parseArgs message in the error text.","Run the CLI with --help or check the flag definitions passed to parse() to confirm accepted flags.","Quote values containing spaces or special shell characters.","If you own the CLI, mark newly-optional flags lenient (strict: false) or register them in flagDefs."],"exampleFix":"// before\ncli.parse(['--verbos', 'x']); // CliUsageError: Unknown option '--verbos'\n// after\ncli.parse(['--verbose', 'x']);","handlingStrategy":"validation","validationCode":"// pre-validate argv against the CLI's declared flags before parsing\nconst known = new Set(['--verbose', '--config', '--format']);\nconst unknown = args.filter(a => a.startsWith('--') && !known.has(a.split('=')[0]));\nif (unknown.length) console.error(`Unknown flags: ${unknown.join(' ')}`);","typeGuard":null,"tryCatchPattern":"try {\n  const parsed = cli.parse(argv);\n} catch (err) {\n  if (err instanceof CliUsageError) {\n    console.error(`Usage error: ${err.message}`);\n    process.exitCode = 2; // usage exit code, not a crash\n    return;\n  }\n  throw err;\n}","preventionTips":["Consult --help output before adding flags to scripts.","Pin the CLI version in automation to avoid flag-surface changes.","Quote all option values containing spaces or special characters."],"tags":["cli","argument-parsing","usage"],"backgroundTag":"invalid-cli-arguments","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}