vercel/ai · error · InvalidArgumentError

targetLanguage is required for translation model '${this.mod

Error message

targetLanguage is required for translation model '${this.modelId}'.

What it means

OpenAI speech translation requires an explicit target language; unlike transcription, the API does not infer it. doStream of OpenAISpeechTranslationModel validates options.targetLanguage up front and throws InvalidArgumentError if it is null/undefined, since the underlying realtime translation call cannot proceed without it.

Source

Thrown at packages/openai/src/speech-translation/openai-speech-translation-model.ts:70

    config: OpenAISpeechTranslationModelConfig;
  }) {
    return new OpenAISpeechTranslationModel(options.modelId, options.config);
  }

  get provider(): string {
    return this.config.provider;
  }

  constructor(
    readonly modelId: OpenAISpeechTranslationModelId,
    private readonly config: OpenAISpeechTranslationModelConfig,
  ) {}

  async doStream(
    options: SpeechTranslationModelV4StreamOptions,
  ): Promise<Awaited<ReturnType<SpeechTranslationModelV4['doStream']>>> {
    if (options.targetLanguage == null) {
      throw new InvalidArgumentError({
        argument: 'targetLanguage',
        message: `targetLanguage is required for translation model '${this.modelId}'.`,
      });
    }

    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
    await parseProviderOptions({
      provider: 'openai',
      providerOptions: options.providerOptions,
      schema: openAISpeechTranslationModelOptions,
    });
    const warnings: SharedV4Warning[] = [];

    validateOpenAISpeechTranslationInputAudioFormat(options.inputAudioFormat);

    if (options.sourceLanguage != null) {
      warnings.push({
        type: 'unsupported',

View on GitHub (pinned to 69428b1f8b)

Solutions

Pass targetLanguage (e.g. 'es', 'fr') in the doStream/call options
Default the language in your app before invoking the model
Validate the options object at the boundary of your application

Example fix

// before
model.doStream({ audio: input })
// after
model.doStream({ audio: input, targetLanguage: 'es' })

Defensive patterns

Strategy: validation

Validate before calling

if (options.targetLanguage == null) {
  throw new Error('targetLanguage must be provided for translation models');
}

Try / catch

try {
  await translationModel.doStream({ ...options, targetLanguage });
} catch (e) {
  if (InvalidArgumentError.isInstance(e) && e.argument === 'targetLanguage') {
    // prompt user for a language or apply a default before retrying
  } else throw e;
}

Prevention

Always set targetLanguage when using translation models (they differ from transcription models)
Use TypeScript's required-property typing instead of optional fields in your options builders
Apply a sensible default language at the application boundary

When it happens

Trigger: Invoking a translation model (openai.translation(...) / SpeechTranslationModelV4 doStream) without providing targetLanguage in the call options, e.g. omitting it or passing null after conditional construction of options.

Common situations: Reusing code written for transcription (which needs no target language) for translation; building options dynamically where targetLanguage depends on optional user input; type loosening via `as any` hiding the missing property.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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