{"record":{"id":"94e5e6c853e1339e","repo":"mastra-ai/mastra","slug":"query-parameters-versionid-and-status-are-mutu-94e5e6","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/network-route.ts","lineNumber":341,"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":323,"sourceCodeEnd":359,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/network-route.ts#L323-L359","documentation":"The network route resolves which agent version to use from either a 'versionId' query parameter or a 'status' query parameter (draft/published). This library throws when both are supplied because the resolution is ambiguous: it cannot decide whether to load a specific version or the latest draft/published one.","triggerScenarios":"Calling a network/agent route with both query params set, e.g. GET /api/network/agents/my-agent?versionId=abc123&status=draft. Any client code that appends a versionId to a URL that already carries a status parameter.","commonSituations":"Manually constructing URLs in scripts or tests where both params are accidentally left in the query string; UI layers merging stale URL state with a newly selected version; caching layers that preserve the full original query string while adding new params.","solutions":["Remove either the versionId or the status query parameter so only one is present.","If targeting a specific version, keep versionId and drop status (versionId takes precedence in intent).","If targeting the current draft or published version, drop versionId and keep status.","Fix client code that concatenates query strings to overwrite params instead of appending."],"exampleFix":"// before\nfetch(`/api/network/agents/${id}?versionId=${versionId}&status=draft`);\n// after\nfetch(`/api/network/agents/${id}?versionId=${versionId}`);","handlingStrategy":"validation","validationCode":"const params = new URLSearchParams(query);\nif (params.has('versionId') && params.has('status')) {\n  throw new Error('versionId and status are mutually exclusive');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use URLSearchParams.set() to overwrite params instead of concatenating strings.","Centralize route URL building in one helper.","Decide per call: either a specific version or a draft/published selector, never both."],"tags":["http","query-parameters","validation","client-sdk"],"backgroundTag":"mutually-exclusive-query-params","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}