mastra-ai/mastra · error · ApiCliError

MISSING_ARGUMENT

MISSING_ARGUMENT

Error message

MISSING_ARGUMENT: Missing required argument <${name}>

What it means

resolvePathParams fills each positional declared by the command descriptor (descriptor.positionals) from the ordered positionalValues list. If the value at a position is missing or empty, it throws MISSING_ARGUMENT naming the expected argument, because the positional is required to build the request URL.

Source

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

  } 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),
    });
  }
}

export function resolvePathParams(
  descriptor: ApiCommandDescriptor,
  positionalValues: string[],
  input?: Record<string, unknown>,
): Record<string, string> {
  const params: Record<string, string> = {};

  descriptor.positionals.forEach((name, index) => {
    const value = positionalValues[index];
    if (!value) {
      throw new ApiCliError('MISSING_ARGUMENT', `Missing required argument <${name}>`, { argument: name });
    }
    params[name] = value;
  });

  for (const name of pathParamNames(descriptor.path)) {
    if (params[name]) continue;
    const value = input?.[name];
    if (typeof value !== 'string' || !value) {
      throw new ApiCliError('MISSING_ARGUMENT', `Missing required argument <${name}>`, { argument: name });
    }
    params[name] = value;
  }

  return params;
}

export function stripPathParamsFromInput(
  input: Record<string, unknown> | undefined,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass all required positionals in order: `mastra api agents get my-agent-id`
2. Check the command help output to see the declared positional list
3. Verify the env variable feeding the positional is non-empty before invoking
4. Supply path params via the JSON --input object as a fallback (see the next branch, which reads input[name] for path params)

Example fix

// before
mastra api agents get
// after
mastra api agents get weather-agent

const required = commandDescriptor.positionals;
if (argv.filter(a => !a.startsWith('-')).length < required.length) {
  throw new Error(`Missing positionals: ${required.slice(argv.length).join(', ')}`);
}

function hasPositionals(args: string[], count: number): args is [string, ...string[]] { return args.length >= count && args.slice(0, count).every(v => v.length > 0); }

try { await runApiCommand(cmd, args); } catch (e) { if (String(e).includes('MISSING_ARGUMENT')) { console.error('Usage:', e.message, '- see `mastra api <cmd> --help`'); } else throw e; }

When it happens

Trigger: Calling a command like `mastra api agents get <agentId>` with too few positionals — e.g. `mastra api agents get` or `mastra api agents get ""` — so positionalValues[index] is undefined/empty for a declared positional.

Common situations: Forgetting an ID the command requires; an empty shell variable (`$AGENT_ID` unset); wrapping the argument in an option flag so the CLI doesn't count it as a positional; reordering arguments by mistake.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Missing value for ${flag}
• No project specified. Pass --project <name|slug|id>, set MAS
• Factory rule version is required.
• Invalid --region "${region}". Expected one of: eu, us.
• ${err instanceof Error ? err.message : String(err)}\nYou can

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