mastra-ai/mastra · error

Expected atleast 3 id parts ${gatewayPrefix}/provider/model,

Error message

Expected atleast 3 id parts ${gatewayPrefix}/provider/model, but only saw ${idParts.length} in ${routerId}

What it means

parseModelRouterId splits a model router ID into providerId and modelId. When a gateway prefix is supplied (other than azure-openai or a provider-equals-gateway gateway), the ID must be a 3-part string of the form `<gatewayPrefix>/<providerId>/<modelId>`. This error is thrown when fewer than 3 slash-separated parts are found, meaning the model ID or provider segment is missing.

Source

Thrown at packages/core/src/llm/model/gateway-resolver.ts:44

  // Provider-equals-gateway: a gateway whose provider id is the same as its
  // gateway id (e.g. amazon-bedrock) uses a 2-part router id (gateway/model),
  // because there is no separate provider segment to namespace. Catalog ids
  // for such gateways are always two parts (model ids contain no slashes).
  if (gatewayPrefix && idParts.length === 2 && idParts[0] === gatewayPrefix) {
    const modelId = idParts[1];
    if (!modelId) {
      throw new Error(`Expected format ${gatewayPrefix}/model, but got ${routerId}`);
    }
    return {
      providerId: gatewayPrefix,
      modelId,
    };
  }

  // Standard 3-part format for other prefixed gateways (Netlify, etc.)
  if (gatewayPrefix && idParts.length < 3) {
    throw new Error(
      `Expected atleast 3 id parts ${gatewayPrefix}/provider/model, but only saw ${idParts.length} in ${routerId}`,
    );
  }

  const providerId = idParts.at(gatewayPrefix ? 1 : 0);
  const modelId = idParts.slice(gatewayPrefix ? 2 : 1).join(`/`);

  if (!routerId.includes(`/`) || !providerId || !modelId) {
    throw new Error(
      `Attempted to parse provider/model from ${routerId} but this ID doesn't appear to contain a provider`,
    );
  }

  return {
    providerId,
    modelId,
  };
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use the full 3-part format gatewayPrefix/provider/model, e.g. 'netlify/openai/gpt-4o' instead of 'netlify/openai'.
2. If the model ID itself contains slashes, verify you are not splitting/truncating the ID before it reaches parseModelRouterId.
3. If this gateway legitimately uses a 2-part gateway/model format (provider equals gateway, like amazon-bedrock), confirm the gateway resolver passes the correct gatewayPrefix so the 2-part branch at line 31 is taken instead.
4. Check where the routerId originates (catalog, config, user input) and validate the segment count before calling the resolver.

Example fix

// before
const model = gateway.resolveModel('netlify/openai');
// after
const model = gateway.resolveModel('netlify/openai/gpt-4o');

function ensureGatewayRouterId(routerId: string, gatewayPrefix?: string): void {
  if (gatewayPrefix && !routerId.startsWith(`${gatewayPrefix}/`)) {
    throw new Error(`Router ID must start with ${gatewayPrefix}/`);
  }
  const parts = routerId.split('/').filter(Boolean);
  if (gatewayPrefix && gatewayPrefix !== 'azure-openai' && parts.length < 3) {
    throw new Error(`Router ID must be ${gatewayPrefix}/provider/model, got: ${routerId}`);
  }
}

function isThreePartRouterId(routerId: string, gatewayPrefix: string): boolean {
  return routerId.startsWith(`${gatewayPrefix}/`) && routerId.split('/').filter(Boolean).length >= 3;
}

try {
  const { providerId, modelId } = parseModelRouterId(routerId, gatewayPrefix);
} catch (e) {
  throw new Error(`Invalid gateway router ID "${routerId}"; expected ${gatewayPrefix}/provider/model`, { cause: e });
}

When it happens

Trigger: Calling parseModelRouterId with a gatewayPrefix (e.g. 'netlify') and a routerId that only has 1 or 2 slash-separated parts, such as 'netlify' or 'netlify/openai' instead of 'netlify/openai/gpt-4o'.

Common situations: Passing a bare model ID like 'gpt-4o' or a partial gateway ID like 'netlify/openai' where a fully prefixed router ID is expected; hand-constructed model IDs; copy-pasting a provider-only model string from another library.

Related errors

• Attempted to parse provider/model from ${routerId} but this
• Expected ${gatewayPrefix}/ in model router ID ${routerId}
• Expected format ${gatewayPrefix}/model, but got ${routerId}
• MODEL_ROUTER_NO_GATEWAY_FOUND
• Invalid state token payload

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