{"record":{"id":"31eed22628b8c1e2","repo":"mastra-ai/mastra","slug":"query-parameters-versionid-and-status-are-mutu","errorCode":null,"errorMessage":"Query parameters \"versionId\" and \"status\" are mutually exclusive","messagePattern":"Query parameters \"versionId\" and \"status\" are mutually exclusive","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/ai-sdk/src/chat-route.ts","lineNumber":712,"sourceCode":"        (contextRequestContext && defaultOptions?.requestContext) ||\n        (contextRequestContext && params.requestContext) ||\n        (defaultOptions?.requestContext && params.requestContext)\n      ) {\n        mastra\n          .getLogger()\n          ?.warn(`Multiple \"requestContext\" sources provided. Using priority: middleware > route options > body.`);\n      }\n\n      if (!agentToUse) {\n        throw new Error('Agent ID is required');\n      }\n\n      // Resolve agent version from query params, falling back to static option\n      const queryVersionId = c.req.query('versionId');\n      const rawStatus = c.req.query('status');\n\n      if (queryVersionId && rawStatus) {\n        throw new Error('Query parameters \"versionId\" and \"status\" are mutually exclusive');\n      }\n\n      if (rawStatus && rawStatus !== 'draft' && rawStatus !== 'published') {\n        throw new Error('Query parameter \"status\" must be \"draft\" or \"published\"');\n      }\n\n      const queryStatus = rawStatus as 'draft' | 'published' | undefined;\n      const effectiveAgentVersion: AgentVersionOptions | undefined = queryVersionId\n        ? { versionId: queryVersionId }\n        : queryStatus\n          ? { status: queryStatus }\n          : agentVersion;\n\n      const handlerOptions = {\n        mastra,\n        agentId: agentToUse,\n        agentVersion: effectiveAgentVersion,\n        params: {","sourceCodeStart":694,"sourceCodeEnd":730,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/chat-route.ts#L694-L730","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove either versionId or status from the request — keep only one","Use versionId alone to pin an exact version; use status alone ('draft' or 'published') to select a channel","Fix the client/query builder so it does not append both params","Note that status must also be exactly 'draft' or 'published' or a follow-up error is thrown"],"exampleFix":"// before\n/api/chat/my-agent?versionId=v_123&status=published\n// after\n/api/chat/my-agent?versionId=v_123\n// or\n/api/chat/my-agent?status=published","handlingStrategy":"validation","validationCode":"const params = new URLSearchParams(query);\nif (params.has('versionId') && params.has('status')) {\n  throw new Error('Use either versionId or status, not both');\n}","typeGuard":"function hasSingleVersionSelector(q: { versionId?: string; status?: string }): boolean {\n  return !(q.versionId && q.status);\n}","tryCatchPattern":"try {\n  const res = await fetch(url, init);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('mutually exclusive')) {\n    // strip one of the params and retry\n  }\n  throw err;\n}","preventionTips":["Centralize chat-route URL building in one helper that enforces one version selector","Document whether your app pins versions (versionId) or channels (status) and stick to one","If status is sent, validate it is exactly 'draft' or 'published' before requesting","Audit middleware/gateways that may inject default query params"],"tags":["ai-sdk","query-params","validation","conflicting-parameters"],"backgroundTag":"conflicting-query-params","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}