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

Source

Thrown at client-sdks/ai-sdk/src/network-route.ts:341

        (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 the versionId or the status query parameter so only one is present.
2. If targeting a specific version, keep versionId and drop status (versionId takes precedence in intent).
3. If targeting the current draft or published version, drop versionId and keep status.
4. Fix client code that concatenates query strings to overwrite params instead of appending.

Example fix

// before
fetch(`/api/network/agents/${id}?versionId=${versionId}&status=draft`);
// after
fetch(`/api/network/agents/${id}?versionId=${versionId}`);

const params = new URLSearchParams(query);
if (params.has('versionId') && params.has('status')) {
  throw new Error('versionId and status are mutually exclusive');
}

When it happens

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

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

Related errors

• Query parameter "status" must be "draft" or "published"
• Query parameter "status" must be "draft" or "published"
• Agent ID is required
• Missing required query param: ${label}
• ${label} must be relative

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