mastra-ai/mastra · error

Query parameters "versionId" and "status" are mutually exclu

Error message

Query parameters "versionId" and "status" are mutually exclusive

What it means

The chat route supports targeting a specific agent version via versionId or a channel ('draft'/'published') via status. These are two mutually exclusive selection modes: an exact version ID versus a status alias. Supplying both is ambiguous, so the handler rejects the request.

Source

Thrown at client-sdks/ai-sdk/src/chat-route.ts:712

        (contextRequestContext && defaultOptions?.requestContext) ||
        (contextRequestContext && params.requestContext) ||
        (defaultOptions?.requestContext && params.requestContext)
      ) {
        mastra
          .getLogger()
          ?.warn(`Multiple "requestContext" sources provided. Using priority: middleware > route options > body.`);
      }

      if (!agentToUse) {
        throw new Error('Agent ID is required');
      }

      // Resolve agent version from query params, falling back to static option
      const queryVersionId = c.req.query('versionId');
      const rawStatus = c.req.query('status');

      if (queryVersionId && rawStatus) {
        throw new Error('Query parameters "versionId" and "status" are mutually exclusive');
      }

      if (rawStatus && rawStatus !== 'draft' && rawStatus !== 'published') {
        throw new Error('Query parameter "status" must be "draft" or "published"');
      }

      const queryStatus = rawStatus as 'draft' | 'published' | undefined;
      const effectiveAgentVersion: AgentVersionOptions | undefined = queryVersionId
        ? { versionId: queryVersionId }
        : queryStatus
          ? { status: queryStatus }
          : agentVersion;

      const handlerOptions = {
        mastra,
        agentId: agentToUse,
        agentVersion: effectiveAgentVersion,
        params: {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Remove either versionId or status from the request — keep only one
2. Use versionId alone to pin an exact version; use status alone ('draft' or 'published') to select a channel
3. Fix the client/query builder so it does not append both params
4. Note that status must also be exactly 'draft' or 'published' or a follow-up error is thrown

Example fix

// before
/api/chat/my-agent?versionId=v_123&status=published
// after
/api/chat/my-agent?versionId=v_123
// or
/api/chat/my-agent?status=published

const params = new URLSearchParams(query);
if (params.has('versionId') && params.has('status')) {
  throw new Error('Use either versionId or status, not both');
}

function hasSingleVersionSelector(q: { versionId?: string; status?: string }): boolean {
  return !(q.versionId && q.status);
}

try {
  const res = await fetch(url, init);
} catch (err) {
  if (err instanceof Error && err.message.includes('mutually exclusive')) {
    // strip one of the params and retry
  }
  throw err;
}

When it happens

Trigger: Appending both query params to the chat route URL: GET /api/chat/my-agent?versionId=abc&status=published; a client that always appends its stored versionId while a layer adds a default status param.

Common situations: Custom resume/version-pinning UIs that merge query params without deduplication; API gateways that inject default query params; hand-written URLs combining examples from two different docs sections.

Related errors

• runId is required when resumeData is provided
• Messages must be an array of UIMessage objects
• Query parameter "status" must be "draft" or "published"
• UI Messages require a data property when using data- prefixe
• Missing required query param: ${label}

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