mastra-ai/mastra · error · Error

Invalid model configuration provided

Error message

Invalid model configuration provided

What it means

resolveModelConfig accepts either a magic string (e.g. 'openai/gpt-4o') or an OpenAI-compatible config object and returns a ModelRouterLanguageModel; any other shape is unsupported and triggers this generic Error with no detail about what was received.

Source

Thrown at packages/core/src/llm/model/resolve-model.ts:141

    }
    // Unknown specificationVersion from a third-party provider (e.g. ollama-ai-provider-v2).
    // If the model has doStream/doGenerate methods, wrap it as a modern model
    // to prevent the stream()/streamLegacy() catch-22 where neither method accepts the model.
    if (typeof (modelConfig as any).doStream === 'function' && typeof (modelConfig as any).doGenerate === 'function') {
      return new AISDKV5LanguageModel(modelConfig as unknown as LanguageModelV2);
    }
    return modelConfig as MastraLanguageModel;
  }

  const gatewayRecord = mastra?.listGateways();
  const customGateways = gatewayRecord ? Object.values(gatewayRecord) : undefined;

  // If it's a string (magic string like "openai/gpt-4o") or OpenAICompatibleConfig, create ModelRouterLanguageModel
  if (typeof modelConfig === 'string' || isOpenAICompatibleObjectConfig(modelConfig)) {
    return new ModelRouterLanguageModel(modelConfig, customGateways);
  }

  throw new Error('Invalid model configuration provided');
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a router string like 'openai/gpt-4o' or a valid OpenAICompatibleConfig object
2. Log/inspect the runtime modelConfig value — the error message does not include it
3. Check for undefined/null from config loaders before calling resolveModelConfig
4. Verify legacy model instances are migrated to the supported config shapes

Example fix

// before
const model = await loadConfig(); // could be undefined
resolveModelConfig(model);
// after
const cfg = await loadConfig();
if (typeof cfg !== 'string' && !(cfg && typeof cfg === 'object' && 'url' in cfg)) {
  throw new Error(`Unsupported model config: ${JSON.stringify(cfg)}`);
}
resolveModelConfig(cfg);

function isValidModelConfig(c: unknown): boolean {
  return typeof c === 'string' || (typeof c === 'object' && c !== null && 'url' in c);
}

interface OpenAICompatibleConfig { url: string; [k: string]: unknown }
function isOpenAICompatibleConfig(c: unknown): c is string | OpenAICompatibleConfig {
  return typeof c === 'string' ||
    (typeof c === 'object' && c !== null && typeof (c as any).url === 'string');
}

try {
  const model = resolveModelConfig(cfg as any);
} catch (e) {
  if (e instanceof Error && e.message === 'Invalid model configuration provided') {
    console.error('Bad model config:', JSON.stringify(cfg));
  }
  throw e;
}

When it happens

Trigger: Passing a model config that is neither a string nor an OpenAI-compatible object into resolveModelConfig — e.g. an arbitrary object, undefined from a bad lookup, a provider SDK client instance, or a malformed nested config.

Common situations: Config loaded from JSON/env where the model field is null/undefined; passing an OpenAI SDK client object instead of a string; refactors that changed the model config shape; forgetting to upgrade a legacy model object format.

Related errors

• Plugin entry must be a .ts file
• Invalid model provided. Model must be a MastraLanguageModel
• Agent model not available
• No enabled models available for execution
• AGENT_FS_ROUTING_MODEL_REQUIRED

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