mastra-ai/mastra · error

Missing value for ${flag}

Error message

Missing value for ${flag}

What it means

readFlag is a tiny CLI arg parser in the TUI entrypoint: when a --flag is present but the following token is missing or is itself another flag (starts with '--'), it throws 'Missing value for <flag>' instead of silently treating the flag as undefined.

Source

Thrown at mastracode/tui/src/main.ts:296

  const dir = args[1];
  if (!dir) {
    process.stderr.write('Usage: mastracode plugin scaffold <dir> [--id acme.foo] [--name "Foo Tools"]\n');
    process.exit(1);
  }

  const id = readFlag(args, '--id');
  const name = readFlag(args, '--name');
  const targetDir = scaffoldPlugin(dir, { ...(id ? { id } : {}), ...(name ? { name } : {}) });
  process.stdout.write(`${formatScaffoldSuccess(targetDir)}\n`);
}

function readFlag(args: string[], flag: string): string | undefined {
  const index = args.indexOf(flag);
  if (index === -1) return undefined;
  const value = args[index + 1];
  if (!value || value.startsWith('--')) {
    throw new Error(`Missing value for ${flag}`);
  }
  return value;
}

const handleFatalError = createOneShotFatalErrorHandler((error: unknown): void => {
  // Always write to real stderr, even if console.error was overridden
  const write = (msg: string) => {
    try {
      process.stderr.write(msg + '\n');
    } catch {}
  };

  if (hasEconnrefused(error)) {
    const settings = loadSettings();
    const connStr = settings.storage?.pg?.connectionString;
    const target = connStr ?? 'localhost:5432';
    write(
      `\nFailed to connect to PostgreSQL at ${target}.` +

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass the value right after the flag: `mastracode --model openai/gpt-4o`
2. Quote values that start with dashes: `--name "--special"`
3. Fix the script/alias so the value token is actually emitted

Example fix

// before
mastracode --model --thread t1
// after
mastracode --model openai/gpt-4o --thread t1

function requireFlagValue(args: string[], flag: string): string {
  const i = args.indexOf(flag);
  if (i === -1) throw new Error(`${flag} is required`);
  const v = args[i + 1];
  if (!v || v.startsWith('--')) throw new Error(`Missing value for ${flag}`);
  return v;
}

try {
  const model = readFlag(process.argv.slice(2), '--model');
} catch (e) {
  console.error((e as Error).message, '\nUsage: mastracode --model <model-id>');
  process.exit(1);
}

When it happens

Trigger: Invoking the TUI like `mastracode --model` (nothing after) or `mastracode --name --thread abc` where the next token is another flag, so the intended value was never supplied.

Common situations: Truncated copy-paste of a launch command; shell alias dropping the value; forgetting that a value starting with '-' needs quoting or an '=' form; scripting that conditionally appends the value and emits nothing.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• MISSING_ARGUMENT
• Invalid state token payload
• Failed to parse A2A stream event: ${error instanceof Error ?
• Unsupported GitHub review state: ${state}
• Linear project source id is invalid.

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