{"record":{"id":"ba53578fdc239782","repo":"mastra-ai/mastra","slug":"missing-argument","errorCode":"MISSING_ARGUMENT","errorMessage":"MISSING_ARGUMENT: Missing required argument <${name}>","messagePattern":"MISSING_ARGUMENT: Missing required argument <(.+?)>","errorType":"error_code","errorClass":"ApiCliError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/api/client.ts","lineNumber":68,"sourceCode":"    throw toApiCliError(error);\n  } finally {\n    clearTimeout(timeout);\n  }\n}\n\nexport function buildUrl(\n  baseUrl: string,\n  path: string,\n  pathParams: Record<string, string>,\n  input?: Record<string, unknown>,\n  apiPrefix?: string,\n): string {\n  const pathParamNames = new Set<string>();\n  const resolvedPath = path.replace(/:([A-Za-z0-9_]+)/g, (_, name: string) => {\n    pathParamNames.add(name);\n    const value = pathParams[name];\n    if (!value) {\n      throw new ApiCliError('MISSING_ARGUMENT', `Missing required argument <${name}>`, { argument: name });\n    }\n    return encodeURIComponent(value);\n  });\n  const url = new URL(joinUrl(baseUrl, resolvedPath, apiPrefix));\n\n  for (const [key, value] of Object.entries(pathParams)) {\n    if (!pathParamNames.has(key)) url.searchParams.set(key, value);\n  }\n\n  if (input) {\n    for (const [key, value] of Object.entries(input)) {\n      if (value === undefined || value === null) continue;\n      url.searchParams.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));\n    }\n  }\n\n  return url.toString();\n}","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/api/client.ts#L50-L86","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Supply the missing argument shown in the error message (e.g. pass the agent/tool/workflow id) to the CLI command.","Check the command's help output (`mastra api <command> --help`) for the expected positional argument order and names.","If scripting, ensure the shell variable feeding the argument is non-empty before invoking the CLI.","Verify you are using the correct subcommand — the id may belong to a different route than the one invoked."],"exampleFix":"// before\nmastra api get-agent\n// Error: Missing required argument <agentId>\n// after\nmastra api get-agent my-agent-id","handlingStrategy":"validation","validationCode":"// Extract :param names and confirm all are provided before calling the command\nfunction missingPathParams(path: string, params: Record<string, string>): string[] {\n  return [...path.matchAll(/:([A-Za-z0-9_]+)/g)]\n    .map((m) => m[1])\n    .filter((name) => !params[name]);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const url = buildUrl(baseUrl, descriptor.path, pathParams, queryInput, apiPrefix);\n} catch (e) {\n  if (e instanceof ApiCliError && e.code === 'MISSING_ARGUMENT') {\n    console.error(`Please supply --argument ${e.details.argument}`);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Read `mastra api <command> --help` to see required positional arguments before invoking.","In scripts, assert id-bearing shell variables are non-empty (`: \"${AGENT_ID:?missing}\"`).","Validate that user-supplied ids match the route you are targeting (agent id vs workflow id).","Pre-resolve path params in a wrapper that checks missingPathParams before invoking the CLI."],"tags":["cli","argument-validation","url"],"backgroundTag":"missing-required-argument","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}