{"record":{"id":"624433588a15e625","repo":"mastra-ai/mastra","slug":"flag-must-be-one-of-allowed-join","errorCode":null,"errorMessage":"${flag} must be one of: ${allowed.join(', ')}","messagePattern":"(.+?) must be one of: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"mastracode/sdk/src/headless/flags.ts","lineNumber":25,"sourceCode":" *   2. per-flag value coercion + validation, and\n *   3. the `--help` usage text.\n *\n * Adding a flag means adding one row here; parsing, validation, and the usage\n * listing all follow automatically.\n */\nimport type { OutputMode } from './cli.js';\nimport type { PermissionMode, RunMode, ThinkingLevel } from './types.js';\nimport { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS } from './types.js';\n\nexport 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  },","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/headless/flags.ts#L7-L43","documentation":"The validate.enum() helper in headless/flags.ts restricts a flag's raw string value to a fixed set of allowed literals and throws when the value is outside that set. It is used as the parser for browser-tool input schemas (goto/click/press/select/scroll/dialog), so an invalid literal fails at flag/argument parsing with a message listing the permitted values.","triggerScenarios":"Supplying a value not in the allowed list to a flag parsed by validate.enum — e.g. a press key, dialog action, or scroll direction literal that is misspelled, differently cased ('Enter' vs 'enter'), or from an outdated flag name.","commonSituations":"Typo in CLI input schemas for browser actions; case-sensitivity mismatches; docs/examples referencing literals removed or renamed in a newer SDK version; passing free-form user text where an enum literal is required.","solutions":["Use exactly one of the literals listed in the error message (match spelling and case).","Normalize user input (trim + lowercase) before passing it to the flag.","Update automation scripts if the allowed literal set changed in a newer SDK version."],"exampleFix":"// before\n--press-key return\n// after\n--press-key enter  // one of the allowed literals","handlingStrategy":"validation","validationCode":"const ALLOWED = ['enter', 'escape', 'tab']; // per flag's allowed set\nif (!ALLOWED.includes(raw)) {\n  throw new Error(`press-key must be one of: ${ALLOWED.join(', ')}`);\n}","typeGuard":"function isAllowedLiteral<T extends string>(allowed: readonly T[]) {\n  return (v: unknown): v is T => typeof v === 'string' && (allowed as readonly string[]).includes(v);\n}","tryCatchPattern":"try {\n  parsed = parseFlag('press-key', raw);\n} catch (err) {\n  console.error(`${err.message}`); // lists allowed values\n  process.exit(2);\n}","preventionTips":["Keep a typed constant of allowed literals in your automation scripts and use it to build inputs.","Normalize user input (trim, lowercase) before passing enum-ish flags.","Re-check the allowed set after SDK upgrades; literal lists can change."],"tags":["cli","validation","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}