mastra-ai/mastra · error · ApiCliError

MISSING_ARGUMENT

MISSING_ARGUMENT

Error message

MISSING_ARGUMENT: Missing required argument <${name}>

What it means

buildUrl expands `:name` placeholders in a descriptor's route path using the provided pathParams map. If a placeholder has no corresponding non-empty value, it throws ApiCliError('MISSING_ARGUMENT', ...) naming the argument. This guarantees the CLI never sends a request to an unresolved templated path like /agents/:id.

Source

Thrown at packages/cli/src/commands/api/client.ts:68

    throw toApiCliError(error);
  } finally {
    clearTimeout(timeout);
  }
}

export function buildUrl(
  baseUrl: string,
  path: string,
  pathParams: Record<string, string>,
  input?: Record<string, unknown>,
  apiPrefix?: string,
): string {
  const pathParamNames = new Set<string>();
  const resolvedPath = path.replace(/:([A-Za-z0-9_]+)/g, (_, name: string) => {
    pathParamNames.add(name);
    const value = pathParams[name];
    if (!value) {
      throw new ApiCliError('MISSING_ARGUMENT', `Missing required argument <${name}>`, { argument: name });
    }
    return encodeURIComponent(value);
  });
  const url = new URL(joinUrl(baseUrl, resolvedPath, apiPrefix));

  for (const [key, value] of Object.entries(pathParams)) {
    if (!pathParamNames.has(key)) url.searchParams.set(key, value);
  }

  if (input) {
    for (const [key, value] of Object.entries(input)) {
      if (value === undefined || value === null) continue;
      url.searchParams.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
    }
  }

  return url.toString();
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Supply the missing argument shown in the error message (e.g. pass the agent/tool/workflow id) to the CLI command.
2. Check the command's help output (`mastra api <command> --help`) for the expected positional argument order and names.
3. If scripting, ensure the shell variable feeding the argument is non-empty before invoking the CLI.
4. Verify you are using the correct subcommand — the id may belong to a different route than the one invoked.

Example fix

// before
mastra api get-agent
// Error: Missing required argument <agentId>
// after
mastra api get-agent my-agent-id

// Extract :param names and confirm all are provided before calling the command
function missingPathParams(path: string, params: Record<string, string>): string[] {
  return [...path.matchAll(/:([A-Za-z0-9_]+)/g)]
    .map((m) => m[1])
    .filter((name) => !params[name]);
}

try {
  const url = buildUrl(baseUrl, descriptor.path, pathParams, queryInput, apiPrefix);
} catch (e) {
  if (e instanceof ApiCliError && e.code === 'MISSING_ARGUMENT') {
    console.error(`Please supply --argument ${e.details.argument}`);
  } else {
    throw e;
  }
}

When it happens

Trigger: Invoking an API command whose descriptor path contains `:param` (e.g. /api/agents/:agentId) while the parsed pathParams map omits that key or maps it to an empty string — typically because the user omitted the required positional/flag argument.

Common situations: Running `mastra api get-agent` without the agent id positional; scripting the CLI where a shell variable holding the id is empty; typos in the argument name so the value lands in the wrong key of pathParams.

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

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

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