mastra-ai/mastra · error · MastraError

MODEL_ROUTER_NO_GATEWAY_FOUND

MODEL_ROUTER_NO_GATEWAY_FOUND

Error message

No Mastra model router gateway found for model id ${gatewayId}

What it means

findGatewayForModel could not resolve any registered gateway capable of serving the given model id. After checking all gateways (and falling back to the models.dev provider registry), none matched, so the model-router throws a USER-category MastraError. This usually means the model id is malformed or its provider is unknown.

Source

Thrown at packages/core/src/llm/model/gateways/gateway-helpers.ts:53

  });
  if (prefixedGateway) {
    return prefixedGateway;
  }

  // Then check gateways that explicitly claim this (possibly unprefixed) model
  // id, e.g. a gateway that authenticates a bare `anthropic/...` id via OAuth.
  const claimingGateway = gateways.find(g => getGatewayId(g) !== 'models.dev' && g.handlesModel?.(gatewayId) === true);
  if (claimingGateway) {
    return claimingGateway;
  }

  // Then check models.dev (provider registry without prefix)
  const modelsDevGateway = gateways.find(g => getGatewayId(g) === 'models.dev');
  if (modelsDevGateway) {
    return modelsDevGateway;
  }

  throw new MastraError({
    id: 'MODEL_ROUTER_NO_GATEWAY_FOUND',
    category: 'USER',
    domain: 'MODEL_ROUTER',
    text: `No Mastra model router gateway found for model id ${gatewayId}`,
  });
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Correct the model id spelling and use a known prefix (openai/gpt-4o, anthropic/claude-...).
2. Register the models.dev gateway (or the specific provider gateway) with the model router.
3. If it's a custom model, add a provider config covering it or route it explicitly.
4. Check getGatewayId() matching logic: ensure the id's prefix corresponds to a registered gateway id.

Example fix

// before
router.findGatewayForModel('gpt-4o-custom'); // no gateway owns this id
// after
router.findGatewayForModel('openai/gpt-4o');
// or register: new MastraModelRouter({ gateways: [new ModelsDevGateway(), ...] })

function hasKnownGatewayPrefix(modelId, gatewayIds) {
  const prefix = modelId.split('/')[0];
  return gatewayIds.includes(prefix) || gatewayIds.includes('models.dev');
}
if (!hasKnownGatewayPrefix('openai/gpt-4o', ['models.dev'])) throw new Error('No gateway registered for this model id prefix');

function isRoutedModelId(id) { return typeof id === 'string' && /^[\w.-]+\/[\w.:-]+$/.test(id); }

try {
  const gw = findGatewayForModel(modelId);
} catch (e) {
  if (e.id === 'MODEL_ROUTER_NO_GATEWAY_FOUND') {
    console.error(`Unknown model id '${modelId}'. Register a gateway or fix the provider prefix.`);
    throw new UserInputError(e.message);
  }
  throw e;
}

When it happens

Trigger: Calling findGatewayForModel with a gatewayId/model id that no gateway claims: e.g. 'my-model' with no prefix matching any gateway, an unsupported provider prefix like 'unknown-provider/gpt-x', or the models.dev registry gateway not registered.

Common situations: Typo in the model id ('gtp-4o'); using a provider prefix that isn't registered; custom model ids not added to models.dev; forgetting to register the models.dev gateway.

Related errors

• Invalid model string format: "${config}". Expected format: "
• Invalid model string format: "${config.id}". Expected format
• Invalid model string format: "${config.id}". Expected format
• Expected atleast 3 id parts ${gatewayPrefix}/provider/model,
• Attempted to parse provider/model from ${routerId} but this

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