mastra-ai/mastra · error · HTTPException

Responses route could not determine the effective model for

Error message

Responses route could not determine the effective model for this request

What it means

prepareCreateResponseRequest resolves the effective model for the responses route and requires it to expose a modelId. When the resolved model has no modelId (model resolution returned a partial/unknown descriptor), the route throws HTTP 500 rather than dispatch to a model it cannot identify.

Source

Thrown at packages/server/src/server/handlers/responses.ts:713

  const resolvedModel = await agent.getModel({
    requestContext,
    modelConfig: body.model,
  });
  const responseModel =
    body.model ??
    (() => {
      if (resolvedModel.provider && resolvedModel.modelId) {
        const publicProviderId = resolvedModel.provider.includes('.')
          ? resolvedModel.provider.split('.')[0]!
          : resolvedModel.provider;
        return `${publicProviderId}/${resolvedModel.modelId}`;
      }

      if (resolvedModel.modelId) {
        return resolvedModel.modelId;
      }

      throw new HTTPException(500, {
        message: 'Responses route could not determine the effective model for this request',
      });
    })();
  const shouldStore = body.store ?? false;
  const needsMemoryStore = shouldStore || Boolean(body.conversation_id) || Boolean(body.previous_response_id);
  const agentMemoryStore = needsMemoryStore
    ? await resolveAgentMemoryStore({
        agent,
        requestContext,
        errorMessage: body.previous_response_id
          ? 'previous_response_id requires the target agent to have memory storage configured'
          : shouldStore
            ? 'Stored responses require the target agent to have memory storage configured'
            : 'conversation_id requires the target agent to have memory storage configured',
      })
    : null;
  const configuredTools = mapMastraToolsToResponseTools(
    (await Promise.resolve(agent.listTools({ requestContext }))) as Record<string, unknown>,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Fix the agent's model configuration so it resolves to a concrete model (e.g. 'openai/gpt-4o') and required provider env vars are set.
2. Log/inspect the resolvedModel object returned by the agent's resolution path to see why modelId is empty.
3. Upgrade or align @mastra/core and @mastra/server versions so model resolution APIs match.
4. Use an explicitly constructed MastraLanguageModel (provider constructor) instead of an unresolvable string alias.

Example fix

// before
new Agent({ name: 'a', instructions: '...', model: 'my-alias' }) // alias not resolvable
// after
new Agent({ name: 'a', instructions: '...', model: 'openai/gpt-4o' })

// before calling the route, ensure the agent resolves a concrete model
const model = await agent.getModels?.() ?? agent.model;
const modelId = typeof model === 'string' ? model : model?.modelId;
if (!modelId) throw new Error(`Agent ${agentId} has no resolvable model id`);

function hasModelId(m: unknown): m is { modelId: string } {
  return typeof m === 'object' && m !== null && 'modelId' in m && typeof (m as any).modelId === 'string' && (m as any).modelId.length > 0;
}

try {
  const res = await client.createResponse(body);
} catch (e) {
  if (isHttpError(e, 500) && /effective model/.test(e.message)) {
    throw new Error(`Agent model misconfigured: ${e.message}`); // fix model config server-side
  }
  throw e;
}

When it happens

Trigger: POST to the responses route where the agent's model resolution produces an object whose modelId is falsy — e.g. an agent configured with a provider that did not fully resolve, or a model specified via config/context that the route's resolution step cannot turn into a concrete model id.

Common situations: Agent configured with an unsupported or dynamic model entry (e.g. string gateway alias that failed to resolve); version mismatch where the core model resolution API changed shape; custom model wrapper omitting modelId; environment variables for the provider missing so resolution falls back to an unresolvable placeholder.

Related errors

• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• No model available: this run started without a controller se
• ModelByInputTokens requires inputTokens for resolution
• Subconscious curate requires the main agent to resolve its m

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