mastra-ai/mastra · error · HTTPException

${error.message}

Error message

${error.message}

What it means

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.

Source

Thrown at packages/server/src/server/handlers/agents.ts:1882

/**
 * Maps a rejected `result.accepted` (signal/message routing) to an HTTP error.
 *
 * `accepted` only rejects on a setup/misconfig failure surfaced before the run
 * starts (e.g. no model selected, request-context validation, FGA denied) — these
 * are tagged `ErrorCategory.USER` and are the caller's fault, so they map to 400.
 * Anything else falls through to `handleError` (500 by default, or the error's own
 * status). Run/generation errors never reject `accepted`; they surface on the
 * `wake` output stream instead.
 */
function handleSignalRoutingError(error: unknown, defaultMessage: string): never {
  if (
    error instanceof MastraError &&
    error.category === ErrorCategory.USER &&
    !(error as { status?: unknown }).status &&
    !(error as { details?: { status?: unknown } }).details?.status
  ) {
    throw new HTTPException(400, { message: error.message, cause: error });
  }
  return handleError(error, defaultMessage);
}

const sendAgentMessageResponseSchema = sendAgentSignalResponseSchema;

export const SEND_AGENT_SIGNAL_ROUTE: ServerRoute<
  InferParams<typeof agentIdPathParams, undefined, typeof sendAgentSignalBodySchema>,
  z.infer<typeof sendAgentSignalResponseSchema>,
  'json',
  RouteSchemas<
    typeof agentIdPathParams,
    undefined,
    typeof sendAgentSignalBodySchema,
    typeof sendAgentSignalResponseSchema
  >,
  'POST',
  '/agents/:agentId/signals'

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read error.message and cause in the response to identify which input core rejected
2. Fix the offending request field (agentId, threadId, resourceId, body payload) flagged by the message
3. 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

Example fix

// before
await fetch('/api/agents/my-agent/stream', { method: 'POST', body: JSON.stringify({}) });
// after
await fetch('/api/agents/my-agent/stream', {
  method: 'POST',
  body: JSON.stringify({ messages: [{ role: 'user', content: 'hi' }] }),
});

function assertValidAgentRequest(body) {
  if (!body || typeof body !== 'object') throw new Error('request body required');
  if (body.agentId && typeof body.agentId !== 'string') throw new Error('agentId must be a string');
}

function isMastraUserError(e: unknown): e is MastraError & { category: typeof ErrorCategory.USER } {
  return e instanceof MastraError && e.category === ErrorCategory.USER;
}

try {
  await callAgentApi();
} catch (e) {
  if (e instanceof MastraError && e.category === ErrorCategory.USER) {
    console.error('Invalid request:', e.message, e.cause);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot delete the active version. Activate a different versi
• conversation_id and previous_response_id must reference the
• conversation_id requires the target agent to have memory con
• Responses requests require an agent_id
• ${errorMessage}

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