What causes "Missing required argument: ${arg.name}" in mastra-ai/mastra?

Inspect the prompt's `arguments` definition (from prompts/list) and supply every argument with required: true

mastra-ai/mastra · error · ProtocolError

Missing required argument: ${arg.name}

Error message

Missing required argument: ${arg.name}

What it means

After finding the requested prompt, MCPServer validates each prompt argument declared `required: true` in the prompt's `arguments` definition. This MCP ProtocolError (InvalidParams, -32602) is thrown when the caller omits that argument or passes null/undefined. It mirrors JSON-RPC invalid-params semantics for prompt invocation.

Source

Thrown at packages/mcp/src/server/server.ts:1449

      serverInstance.setRequestHandler(
        'prompts/get',
        async (request: { params: { name: string; arguments?: any } }, ctx) => {
          const startTime = Date.now();
          const { name, arguments: args } = request.params;
          const extra = toMCPRequestHandlerExtra(ctx);
          const prompts = await capturedPromptOptions.listPrompts?.({ extra });
          if (!prompts) throw new Error('Failed to load prompts');
          for (const definedPrompt of prompts) {
            PromptSchema.parse(definedPrompt);
          }
          // Select prompt by name
          const prompt = prompts.find(p => p.name === name);
          if (!prompt) throw new Error(`Prompt "${name}" not found`);
          // Validate required arguments
          if (prompt.arguments) {
            for (const arg of prompt.arguments) {
              if (arg.required && (args?.[arg.name] === undefined || args?.[arg.name] === null)) {
                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Missing required argument: ${arg.name}`);
              }
            }
          }
          try {
            let messages: any[] = [];
            if (capturedPromptOptions.getPromptMessages) {
              messages = await capturedPromptOptions.getPromptMessages({
                name,
                version: prompt.version,
                args,
                extra,
              });
            }
            const duration = Date.now() - startTime;
            this.logger.info('Prompt retrieved successfully', { prompt: name, duration });
            return { description: prompt.description, messages };
          } catch (error) {
            const duration = Date.now() - startTime;

View on GitHub (pinned to 75dd419e61)

Solutions

Inspect the prompt's `arguments` definition (from prompts/list) and supply every argument with required: true
Ensure the key names match the argument `name` fields exactly
Convert empty/null form values to the expected strings before calling, or prompt the user for the missing value
If you own the prompt definition and the argument should be optional, set required: false

Example fix

// before
await server.getPrompt('code_review', {});
// after
await server.getPrompt('code_review', { file: 'src/index.ts' }); // all required args present

Defensive patterns

Strategy: validation

Validate before calling

function validatePromptArgs(promptDef, args = {}) {
  const missing = (promptDef.arguments ?? [])
    .filter(a => a.required && (args[a.name] === undefined || args[a.name] === null))
    .map(a => a.name);
  if (missing.length) throw new Error(`Missing required prompt arguments: ${missing.join(', ')}`);
}

Try / catch

try {
  const result = await server.getPrompt(name, args);
} catch (e) {
  if (e instanceof ProtocolError && e.code === -32602) {
    // surface which argument is missing: parse e.message 'Missing required argument: X'
  } else throw e;
}

Prevention

Fetch the prompt's arguments definition and render required fields as mandatory in your UI
Never pass null/undefined for unfilled optional form fields — omit the key entirely
Match argument keys exactly to the `name` fields in the prompt definition

When it happens

Trigger: Calling server.getPrompt(name, args) where a prompt argument marked required: true is missing from args, explicitly null, or explicitly undefined; sending a prompts/get JSON-RPC request whose arguments object lacks a required field.

Common situations: Client UI renders only optional fields; args object built from optional form fields where empty values become undefined; key-name mismatch (e.g. 'fileName' vs 'file_name') so the required key is absent; passing an empty object when the prompt requires arguments.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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