What causes "Model could not be resolved" in vercel/ai?

Pass an explicit speech model instance, e.g. openai.speech('tts-1') or openai('tts-1') from the provider's speech factory

vercel/ai · error

Model could not be resolved

Error message

Model could not be resolved

What it means

generateSpeech resolves the provided model via resolveSpeechModel; if the value cannot be resolved to a speech-capable model (e.g. a string id that no provider registry maps to a SpeechModelV*), a plain Error('Model could not be resolved') is thrown before any network request. It guards against calling the speech API with an unusable model value.

Solutions

Pass an explicit speech model instance, e.g. openai.speech('tts-1') or openai('tts-1') from the provider's speech factory
Check that the variable passed as `model` is actually a speech model, not another model type
If passing a string, ensure a default speech model/provider is configured for resolution
Log/inspect the model value just before the call to catch null/undefined

Example fix

// before
await generateSpeech({ model: 'tts-1', text });
// after
import { createOpenAI } from '@ai-sdk/openai';
const openai = createOpenAI();
await generateSpeech({ model: openai.speech('tts-1'), text });

Defensive patterns

Strategy: validation

Validate before calling

import { isSpeechModel } from 'ai'; // or check provider shape
if (model == null || typeof model !== 'object' || !('modelId' in model)) {
  throw new Error('A speech model instance is required');
}

Type guard

function isSpeechModel(m: unknown): m is SpeechModel {
  return m != null && typeof m === 'object' && 'doGenerate' in m && 'modelId' in m;
}

Try / catch

try {
  return await generateSpeech({ model, text });
} catch (e) {
  if (e instanceof Error && e.message === 'Model could not be resolved') {
    throw new Error('Pass a provider speech model, e.g. openai.speech("tts-1")');
  }
  throw e;
}

Prevention

Always pass provider-created speech models (provider.speech(id))
Do not pass raw string ids unless a default provider is configured
Double-check imports so language models are not passed to generateSpeech

When it happens

Trigger: Passing null/undefined as `model`; passing a plain string model id with no default speech provider configured; passing a language/embedding/image model object instead of a SpeechModel; passing an object that fails resolveSpeechModel's shape checks.

Common situations: Reading the model id from env/config and forgetting to call provider(modelId); refactors after provider upgrades where the speech model factory moved; typos in provider instantiation like openai('tts-1') assigned to the wrong variable.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/21f328fc86f46e13. Report an issue: GitHub.

Appendix: source

Thrown at packages/ai/src/generate-speech/generate-speech.ts:121

   *
   * @default 2
   */
  maxRetries?: number;

  /**
   * Abort signal.
   */
  abortSignal?: AbortSignal;

  /**
   * Additional headers to include in the request.
   * Only applicable for HTTP-based providers.
   */
  headers?: Record<string, string>;
}): Promise<SpeechResult> {
  const resolvedModel = resolveSpeechModel(model);
  if (!resolvedModel) {
    throw new Error('Model could not be resolved');
  }

  const headersWithUserAgent = withUserAgentSuffix(
    headers ?? {},
    `ai/${VERSION}`,
  );

  const { retry } = prepareRetries({
    maxRetries: maxRetriesArg,
    abortSignal,
  });

  const result = await retry(() =>
    resolvedModel.doGenerate({
      text,
      voice,
      outputFormat,
      instructions,

View on GitHub (pinned to 69428b1f8b)