mastra-ai/mastra · warning

${flag} must be one of: ${allowed.join(', ')}

Error message

${flag} must be one of: ${allowed.join(', ')}

What it means

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.

Source

Thrown at mastracode/sdk/src/headless/flags.ts:25

 *   2. per-flag value coercion + validation, and
 *   3. the `--help` usage text.
 *
 * Adding a flag means adding one row here; parsing, validation, and the usage
 * listing all follow automatically.
 */
import type { OutputMode } from './cli.js';
import type { PermissionMode, RunMode, ThinkingLevel } from './types.js';
import { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS } from './types.js';

export const VALID_OUTPUTS = ['human', 'json', 'jsonl'] as const;

/** Reusable validators. Each throws a descriptive Error or returns the typed value. */
const validate = {
  /** Restrict to a fixed set of string literals. */
  enum<T extends string>(flag: string, allowed: readonly T[]) {
    return (raw: string): T => {
      if (!(allowed as readonly string[]).includes(raw)) {
        throw new Error(`${flag} must be one of: ${allowed.join(', ')}`);
      }
      return raw as T;
    };
  },
  /** Require a positive (>0) integer. */
  positiveInt(flag: string) {
    return (raw: string): number => {
      const parsed = Number(raw);
      if (!Number.isInteger(parsed) || parsed <= 0) {
        throw new Error(`${flag} must be a positive integer`);
      }
      return parsed;
    };
  },
  /** Pass a string through unchanged. */
  string(raw: string): string {
    return raw;
  },

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use exactly one of the literals listed in the error message (match spelling and case).
2. Normalize user input (trim + lowercase) before passing it to the flag.
3. Update automation scripts if the allowed literal set changed in a newer SDK version.

Example fix

// before
--press-key return
// after
--press-key enter  // one of the allowed literals

const ALLOWED = ['enter', 'escape', 'tab']; // per flag's allowed set
if (!ALLOWED.includes(raw)) {
  throw new Error(`press-key must be one of: ${ALLOWED.join(', ')}`);
}

function isAllowedLiteral<T extends string>(allowed: readonly T[]) {
  return (v: unknown): v is T => typeof v === 'string' && (allowed as readonly string[]).includes(v);
}

try {
  parsed = parseFlag('press-key', raw);
} catch (err) {
  console.error(`${err.message}`); // lists allowed values
  process.exit(2);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported Factory stage: ${stage}
• ${flag} must be a positive integer
• Project name must be 1-214 lowercase characters, start with
• Invalid Mastra project
• Unsupported database kind: ${kind}. Supported kinds: turso,

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/624433588a15e625. Report an issue: GitHub.