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 'status' query parameter on the agent/network route accepts only the literal values 'draft' or 'published'. This library throws when status is present but any other string, because the route cannot map an unknown status to an agent version.

Source

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

        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,
        } as any,
        defaultOptions,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Change the status value to exactly 'draft' or 'published' (lowercase).
2. If you need a specific historical version, use the versionId query parameter instead of status.
3. Validate/normalize the status string in the client before appending it to the URL.
4. Check for typos and casing in URL templates or env-driven config.

Example fix

// before
fetch(`/api/network/agents/${id}?status=${stage}`); // stage = 'production'
// after
fetch(`/api/network/agents/${id}?status=published`);

const allowed = ['draft', 'published'] as const;
type Status = typeof allowed[number];
function assertStatus(s: string): asserts s is Status {
  if (!allowed.includes(s as Status)) throw new Error(`status must be draft|published, got ${s}`);
}

function isAgentStatus(s: unknown): s is 'draft' | 'published' {
  return s === 'draft' || s === 'published';
}

When it happens

Trigger: GET /api/network/agents/my-agent?status=staging, ?status=DRAFT (case-sensitive), ?status=production, or any misspelled value like ?status=pulished.

Common situations: Hand-typed URLs in a browser; environment-specific URL templates that inject a non-supported stage name; case-sensitivity surprises ('Draft' vs 'draft'); copying params from other APIs that use different status vocabularies.

Related errors

• Query parameters "versionId" and "status" are mutually exclu
• 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/d2a50b44b7647ab4. Report an issue: GitHub.