mastra-ai/mastra · error

Invalid model string format: "${config}". Expected format: "

Error message

Invalid model string format: "${config}". Expected format: "provider/model"

What it means

The EmbeddingRouter constructor parses a model string that must be exactly two slash-separated segments: "provider/model" (e.g. "openai/text-embedding-3-small"). If the string contains more than 2 parts (or fewer), and is not a "mastra/..." gateway id, the constructor cannot determine providerId and modelId, so it throws. This fail-fast validation prevents ambiguous provider/model resolution later.

Source

Thrown at packages/core/src/llm/model/embedding-router.ts:145

    let normalizedConfig: {
      providerId: string;
      modelId: string;
      url?: string;
      apiKey?: string;
      headers?: Record<string, string>;
    };

    if (typeof config === 'string') {
      // Parse provider/model or gateway/provider/model from string.
      const parts = config.split('/');
      if (parts[0] === MASTRA_GATEWAY_ID) {
        if (parts.length < 3) {
          throw new Error(`Invalid model string format: "${config}". Expected format: "mastra/provider/model"`);
        }
        normalizedConfig = { providerId: MASTRA_GATEWAY_ID, modelId: parts.slice(1).join('/') };
      } else {
        if (parts.length !== 2) {
          throw new Error(`Invalid model string format: "${config}". Expected format: "provider/model"`);
        }
        const [providerId, modelId] = parts as [string, string];
        normalizedConfig = { providerId, modelId };
      }
    } else if ('providerId' in config && 'modelId' in config) {
      normalizedConfig = {
        providerId: config.providerId,
        modelId: config.modelId,
        url: config.url,
        apiKey: config.apiKey,
        headers: config.headers,
      };
    } else {
      // config has 'id' field
      const parts = config.id.split('/');
      if (parts[0] === MASTRA_GATEWAY_ID) {
        if (parts.length < 3) {
          throw new Error(`Invalid model string format: "${config.id}". Expected format: "mastra/provider/model"`);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Change the string to exactly two segments: "provider/model" (e.g. "openai/text-embedding-3-small").
2. If you intended to use the Mastra gateway, prefix with "mastra/": "mastra/provider/model".
3. If the model id itself contains slashes, pass an object config { providerId, modelId } instead of a slash-delimited string.
4. Trim stray slashes or whitespace around the config string before constructing.

Example fix

// before
new EmbeddingRouter("openai/org/models/text-embedding-3-small");
// after
new EmbeddingRouter("openai/text-embedding-3-small");
// or for slashed model ids:
new EmbeddingRouter({ providerId: "openai", modelId: "org/models/text-embedding-3-small" });

function isValidProviderModelString(s) {
  const parts = s.split('/');
  return parts.length === 2 && parts.every((p) => p.length > 0);
}
if (!isValidProviderModelString(config)) {
  throw new TypeError(`Expected "provider/model", got: ${config}`);
}

function isProviderModel(s) {
  const parts = s.split('/');
  return parts.length === 2 && parts.every((p) => p.length > 0);
}

let router;
try {
  router = new EmbeddingRouter(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('Invalid model string format')) {
    console.error(`Bad model id "${config}": use "provider/model"`);
    router = new EmbeddingRouter({ providerId: config.split('/')[0], modelId: config.split('/').slice(1).join('/') });
  } else throw e;
}

When it happens

Trigger: new EmbeddingRouter({ id: ... }) or string config with a model id containing extra slashes, e.g. "openai/models/text-embedding-3-small" or a full gateway string "mastra/openai/text-embedding" passed where only "provider/model" is accepted.

Common situations: Developers copy a mastra gateway-style model string (3 parts) into an API expecting provider/model; model names containing slashes (Azure deployments, Hugging Face repo paths) pasted without the correct gateway prefix; typos adding an extra '/' segment.

Related errors

• Invalid model string format: "${config.id}". Expected format
• Invalid model string format: "${config.id}". Expected format
• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI

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