{"record":{"id":"0a7d78928dadace8","repo":"mastra-ai/mastra","slug":"error-message-0a7d78","errorCode":null,"errorMessage":"${error.message}","messagePattern":"\\$\\{error\\.message\\}","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/agents.ts","lineNumber":1882,"sourceCode":"\n/**\n * Maps a rejected `result.accepted` (signal/message routing) to an HTTP error.\n *\n * `accepted` only rejects on a setup/misconfig failure surfaced before the run\n * starts (e.g. no model selected, request-context validation, FGA denied) — these\n * are tagged `ErrorCategory.USER` and are the caller's fault, so they map to 400.\n * Anything else falls through to `handleError` (500 by default, or the error's own\n * status). Run/generation errors never reject `accepted`; they surface on the\n * `wake` output stream instead.\n */\nfunction handleSignalRoutingError(error: unknown, defaultMessage: string): never {\n  if (\n    error instanceof MastraError &&\n    error.category === ErrorCategory.USER &&\n    !(error as { status?: unknown }).status &&\n    !(error as { details?: { status?: unknown } }).details?.status\n  ) {\n    throw new HTTPException(400, { message: error.message, cause: error });\n  }\n  return handleError(error, defaultMessage);\n}\n\nconst sendAgentMessageResponseSchema = sendAgentSignalResponseSchema;\n\nexport const SEND_AGENT_SIGNAL_ROUTE: ServerRoute<\n  InferParams<typeof agentIdPathParams, undefined, typeof sendAgentSignalBodySchema>,\n  z.infer<typeof sendAgentSignalResponseSchema>,\n  'json',\n  RouteSchemas<\n    typeof agentIdPathParams,\n    undefined,\n    typeof sendAgentSignalBodySchema,\n    typeof sendAgentSignalResponseSchema\n  >,\n  'POST',\n  '/agents/:agentId/signals'","sourceCodeStart":1864,"sourceCodeEnd":1900,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agents.ts#L1864-L1900","documentation":"This endpoint maps a MastraError thrown by agent code into an HTTP 400 when it is classified as a user error (ErrorCategory.USER) and carries no explicit HTTP status yet. The server deliberately surfaces user-caused errors as client-side 400s so callers know the request itself was wrong, not the server. Any error without a status on the error or its details gets wrapped this way; everything else falls through to the generic handleError path.","triggerScenarios":"Any agent handler that throws a MastraError with category USER and neither error.status nor error.details.status set — e.g. invalid input rejected inside agent/core code paths invoked by the handler.","commonSituations":"Calling an agent API with malformed body fields, nonexistent agent/thread/resource IDs that core validates as user error, or a version mismatch where core throws USER-category validation errors the server doesn't map to a specific status.","solutions":["Read error.message and cause in the response to identify which input core rejected","Fix the offending request field (agentId, threadId, resourceId, body payload) flagged by the message","If you believe this is a server bug (e.g. valid input rejected), check the MastraError category thrown in core and file/verify against the mastra version in use"],"exampleFix":"// before\nawait fetch('/api/agents/my-agent/stream', { method: 'POST', body: JSON.stringify({}) });\n// after\nawait fetch('/api/agents/my-agent/stream', {\n  method: 'POST',\n  body: JSON.stringify({ messages: [{ role: 'user', content: 'hi' }] }),\n});","handlingStrategy":"try-catch","validationCode":"function assertValidAgentRequest(body) {\n  if (!body || typeof body !== 'object') throw new Error('request body required');\n  if (body.agentId && typeof body.agentId !== 'string') throw new Error('agentId must be a string');\n}","typeGuard":"function isMastraUserError(e: unknown): e is MastraError & { category: typeof ErrorCategory.USER } {\n  return e instanceof MastraError && e.category === ErrorCategory.USER;\n}","tryCatchPattern":"try {\n  await callAgentApi();\n} catch (e) {\n  if (e instanceof MastraError && e.category === ErrorCategory.USER) {\n    console.error('Invalid request:', e.message, e.cause);\n  } else throw e;\n}","preventionTips":["Validate request payloads against the endpoint schema before sending","Log error.cause — the original MastraError names the rejected input","Keep client and server packages on the same mastra version to avoid unmapped error categories"],"tags":["http-400","user-error","validation","server"],"backgroundTag":"user-input-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}