mastra-ai/mastra · error · InvalidArgumentError

Choose valid components: ${COMPONENTS.join(', ')}

Error message

Choose valid components: ${COMPONENTS.join(', ')}

What it means

The Mastra CLI throws this error when a --components flag value cannot be parsed into a valid list of components. parseComponents splits the comma-separated value and validates each entry against the known COMPONENTS list before proceeding with scaffolding. It uses commander's InvalidArgumentError so the CLI prints usage help alongside the message.

Source

Thrown at packages/cli/src/commands/utils.ts:80

  if (!isValidEditor(value)) {
    throw new InvalidArgumentError(`Choose a valid value: ${EDITOR.join(', ')}`);
  }
  return value;
}

export function parseSkills(value: string) {
  // Skills flag accepts comma-separated agent names
  return value
    .split(',')
    .map(s => s.trim())
    .filter(Boolean);
}

export function parseComponents(value: string) {
  const parsedValue = value.split(',');

  if (!areValidComponents(parsedValue)) {
    throw new InvalidArgumentError(`Choose valid components: ${COMPONENTS.join(', ')}`);
  }

  return parsedValue;
}

export function parseLlmProvider(value: string) {
  if (!isValidLLMProvider(value)) {
    throw new InvalidArgumentError(`Choose a valid provider: ${LLMProvider.join(', ')}`);
  }
  return value;
}

export function shouldSkipDotenvLoading(): boolean {
  return process.env.MASTRA_SKIP_DOTENV === 'true' || process.env.MASTRA_SKIP_DOTENV === '1';
}

/**
 * Get the version tag (e.g., 'beta', 'latest') for the currently running mastra CLI.

View on GitHub (pinned to 75dd419e61)

Solutions

1. List valid components from the error message and use exactly those spellings, e.g. --components agents,tools,workflows
2. Remove surrounding whitespace: write --components agents,tools not --components 'agents, tools'
3. Run the command with only the components you need or omit the flag to use defaults
4. Check `mastra init --help` for the current accepted component list

Example fix

// before
mastra init --components agent,tool
// after
mastra init --components agents,tools

const COMPONENTS = ['agents', 'tools', 'workflows', 'networks', 'processors'];
const requested = 'agents,tools'.split(',').map(s => s.trim());
const invalid = requested.filter(c => !COMPONENTS.includes(c));
if (invalid.length) throw new Error(`Invalid components: ${invalid.join(', ')}. Valid: ${COMPONENTS.join(', ')}`);

const isComponent = (v: string): v is Component => COMPONENTS.includes(v as Component);

try {
  runCli(['init', '--components', value]);
} catch (e) {
  if (e instanceof InvalidArgumentError && e.message.startsWith('Choose valid components')) {
    console.error(`Bad --components value "${value}". Use: ${COMPONENTS.join(', ')}`);
  } else throw e;
}

When it happens

Trigger: Running `mastra init`/`mastra create` (or any command wiring this option) with --components set to a value not in COMPONENTS, a typo (e.g. 'agents ' with a stray space is fine after split? no — split keeps spaces, so ' agents' fails), an unsupported component name, or a value like 'agent' instead of 'agents'.

Common situations: Typing component names from memory instead of from docs; copying flags from older blog posts where component names changed; including whitespace around commas (split(',') keeps leading/trailing spaces, failing validation); passing plural/singular variants.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• Choose a valid value: ${EDITOR.join(', ')}
• Invalid --region "${region}". Expected one of: eu, us.
• MISSING_ARGUMENT
• Directory not found: ${dirArg}.${hint}
• Choose a valid provider: ${LLMProvider.join(', ')}

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