mastra-ai/mastra · error · ApiCliError

MISSING_INPUT

MISSING_INPUT

Error message

MISSING_INPUT: Command requires a single inline JSON input argument

What it means

parseInput resolves the inline JSON input for an API command descriptor. If the descriptor accepts input and declares inputRequired but the CLI invocation supplies no input string, it throws ApiCliError('MISSING_INPUT') naming the command. This ensures commands that must receive a payload (e.g. execute/run endpoints) cannot be invoked without one.

Source

Thrown at packages/cli/src/commands/api/input.ts:11

import { ApiCliError } from './errors.js';
import type { ApiCommandDescriptor } from './types.js';

export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };

export function parseInput(descriptor: ApiCommandDescriptor, input?: string): Record<string, unknown> | undefined {
  if (!descriptor.acceptsInput) return undefined;

  if (!input) {
    if (descriptor.inputRequired) {
      throw new ApiCliError('MISSING_INPUT', 'Command requires a single inline JSON input argument', {
        command: `mastra api ${descriptor.name}`,
      });
    }
    return undefined;
  }

  try {
    const parsed = JSON.parse(input);
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
      throw new ApiCliError('INVALID_JSON', 'Input JSON must be an object');
    }
    return parsed as Record<string, unknown>;
  } catch (error) {
    if (error instanceof ApiCliError) throw error;
    throw new ApiCliError('INVALID_JSON', 'Input must be valid JSON', {
      message: error instanceof Error ? error.message : String(error),
    });
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Pass a single inline JSON object as the input argument, e.g. `mastra api tool-execute '{"toolInput": ...}'`.
Check `mastra api <command> --help` for the expected input shape documented by the descriptor.
If scripting, guard against empty variables: `[ -n "$JSON" ] || exit 1` before invoking.
If the command does not need input, use a different subcommand — you may have picked an execute-style command that always requires a payload.

Example fix

// before
mastra api tool-execute
// Error: Command requires a single inline JSON input argument
// after
mastra api tool-execute '{"data": {"prompt": "hello"}}'

Defensive patterns

Strategy: validation

Validate before calling

function requireJsonInput(cmd: string, input?: string): Record<string, unknown> {
  if (!input) throw new Error(`mastra api ${cmd} requires an inline JSON argument`);
  const parsed = JSON.parse(input);
  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
    throw new Error('Input must be a JSON object');
  }
  return parsed as Record<string, unknown>;
}

Type guard

function isJsonObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

Try / catch

try {
  const input = parseInput(descriptor, rawInput);
} catch (e) {
  if (e instanceof ApiCliError && e.code === 'MISSING_INPUT') {
    console.error(`Provide JSON input: mastra ${e.details.command} '{...}'`);
  } else {
    throw e;
  }
}

Prevention

Always quote the JSON argument in shell so spaces and braces survive parsing.
Check --help to confirm whether the command requires input before invoking.
In scripts, assert the JSON payload variable is non-empty before calling the CLI.
Parse and validate the JSON with JSON.parse/isJsonObject before passing it through.

When it happens

Trigger: Calling `mastra api <command>` for a descriptor with acceptsInput: true and inputRequired: true (e.g. tool execute, workflow run) without providing the single inline JSON argument.

Common situations: Forgetting the JSON payload entirely (`mastra api tool-execute`); passing an empty string from a shell variable; expecting the command to prompt or use defaults when it requires an explicit JSON object.

Related errors

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