{"record":{"id":"98fff31e73f3c661","repo":"mastra-ai/mastra","slug":"flag-must-be-a-positive-integer","errorCode":null,"errorMessage":"${flag} must be a positive integer","messagePattern":"(.+?) must be a positive integer","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"mastracode/sdk/src/headless/flags.ts","lineNumber":35,"sourceCode":"export const VALID_OUTPUTS = ['human', 'json', 'jsonl'] as const;\n\n/** Reusable validators. Each throws a descriptive Error or returns the typed value. */\nconst validate = {\n  /** Restrict to a fixed set of string literals. */\n  enum<T extends string>(flag: string, allowed: readonly T[]) {\n    return (raw: string): T => {\n      if (!(allowed as readonly string[]).includes(raw)) {\n        throw new Error(`${flag} must be one of: ${allowed.join(', ')}`);\n      }\n      return raw as T;\n    };\n  },\n  /** Require a positive (>0) integer. */\n  positiveInt(flag: string) {\n    return (raw: string): number => {\n      const parsed = Number(raw);\n      if (!Number.isInteger(parsed) || parsed <= 0) {\n        throw new Error(`${flag} must be a positive integer`);\n      }\n      return parsed;\n    };\n  },\n  /** Pass a string through unchanged. */\n  string(raw: string): string {\n    return raw;\n  },\n};\n\n/**\n * One CLI flag. `key` is the long name (e.g. `output`); `field` is the\n * {@link import('./cli.js').HeadlessArgs} property it populates. `coerce`\n * converts the raw string and validates it. Boolean flags omit `coerce` and set\n * `field` to `true` when present.\n */\nexport interface FlagSpec {\n  /** Long flag name without the leading `--`. */","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/headless/flags.ts#L17-L53","documentation":"validate.positiveInt() parses a flag's raw string with Number() and requires the result to be an integer greater than 0, otherwise throwing '${flag} must be a positive integer'. Any non-numeric string, decimal, zero, or negative value fails at parse time.","triggerScenarios":"Passing flags parsed by FLAGS with values like '0', '-1', '3.5', '', or 'many' to numeric options (counts, indices, timeouts) — Number(raw) either yields NaN, a non-integer, or <= 0.","commonSituations":"Users assuming 0 means 'unlimited'; off-by-one negatives from computed values; locale-formatted numbers or units ('1s', '50%'); empty flag values from shell variable expansion of unset variables.","solutions":["Provide an integer >= 1, e.g. --max-steps 5.","Default unset numeric inputs before parsing: value ?? 1.","Strip units/whitespace and parse with Number.parseInt in wrapper scripts before invoking the CLI."],"exampleFix":"// before\nmastracode --headless --max-turns 0 -p \"run\"\n// after\nmastracode --headless --max-turns 5 -p \"run\"","handlingStrategy":"validation","validationCode":"const n = Number(raw);\nif (!Number.isInteger(n) || n <= 0) {\n  throw new Error(`${flag} must be a positive integer`);\n}","typeGuard":"function isPositiveInt(v: unknown): v is number {\n  return typeof v === 'number' && Number.isInteger(v) && v > 0;\n}","tryCatchPattern":"try {\n  parsed = parseFlag('max-turns', raw);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('must be a positive integer')) {\n    parsed = 1; // sane default\n  } else { throw err; }\n}","preventionTips":["Default unset numeric env/shell variables before invoking (value ?? 1).","Strip units and whitespace; parse with Number.parseInt before passing.","Never pass 0 or negatives expecting 'unlimited' semantics — the parser rejects them."],"tags":["cli","validation","numeric"],"backgroundTag":"invalid-positive-integer","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}