mastra-ai/mastra · error

Query parameter "status" must be "draft" or "published"

Error message

Query parameter "status" must be "draft" or "published"

What it means

The chatRoute rejects a request whose `status` query parameter is not exactly "draft" or "published". The route supports version selection for an agent either by explicit versionId or by channel status, and it only accepts these two literal status values; anything else is invalid input and is rejected before any agent work begins.

Source

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

        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: {
          ...params,
          requestContext: effectiveRequestContext,
          abortSignal: c.req.raw.signal,
        } as any,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Send only "draft" or "published" as the status query parameter value
2. Use lowercase, exact spelling — values are compared strictly
3. If you need a specific version, pass versionId instead of status (they are mutually exclusive)
4. URL-encode/trim whitespace; stray spaces cause the mismatch

Example fix

// before
fetch(`/api/chat?status=production`)
// after
fetch(`/api/chat?status=published`)

const STATUS = ['draft','published'];
function assertStatus(s?: string) {
  if (s && !STATUS.includes(s)) throw new Error(`status must be "draft" or "published", got "${s}"`);
}
assertStatus(new URL(url).searchParams.get('status'));

function isAgentVersionStatus(v: unknown): v is 'draft' | 'published' {
  return v === 'draft' || v === 'published';
}

try {
  const res = await fetch(url);
  if (!res.ok) throw new Error(await res.text());
} catch (e) {
  if (e.message.includes('status" must be')) {
    // correct the query param and retry
  }
}

When it happens

Trigger: Calling the chat route with a query string like ?status=latest, ?status=DRAFT, ?status=prod, or any misspelled value while versionId is not provided.

Common situations: Clients hardcoding a status string that drifts from the API contract (e.g. 'production' instead of 'published'), case-sensitivity mistakes, UI dropdowns emitting display labels instead of the literal values, or a stale client built against an older/looser API.

Related errors

• Missing required query param: ${label}
• Query parameters "versionId" and "status" are mutually exclu
• Agent ID is required
• Query parameters "versionId" and "status" are mutually exclu
• Query parameter "status" must be "draft" or "published"

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