vercel/ai · error · InvalidArgumentError

providerOptions.xai.channels is required when providerOption

Error message

providerOptions.xai.channels is required when providerOptions.xai.multichannel is true

What it means

doStream in the xAI transcription model validates providerOptions.xai before sending the request: when multichannel is set to true, the channels option must also be provided because xAI's multichannel transcription requires an explicit channel list. If channels is null/undefined while multichannel is true, an InvalidArgumentError is thrown before any network call.

Source

Thrown at packages/xai/src/xai-transcription-model.ts:194

      },
    };
  }

  async doStream(
    options: TranscriptionModelV4StreamOptions,
  ): Promise<
    Awaited<ReturnType<NonNullable<TranscriptionModelV4['doStream']>>>
  > {
    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
    const warnings: SharedV4Warning[] = [];
    const xaiOptions = await parseProviderOptions({
      provider: 'xai',
      providerOptions: options.providerOptions,
      schema: xaiTranscriptionModelOptionsSchema,
    });

    if (xaiOptions?.multichannel === true && xaiOptions.channels == null) {
      throw new InvalidArgumentError({
        argument: 'providerOptions',
        message:
          'providerOptions.xai.channels is required when providerOptions.xai.multichannel is true',
      });
    }

    if (xaiOptions?.format != null) {
      warnings.push({
        type: 'unsupported',
        feature: 'providerOptions.xai.format',
        details: 'xAI streaming transcription does not support format.',
      });
    }

    if (
      xaiOptions?.audioFormat == null &&
      !isKnownInputAudioFormat(options.inputAudioFormat.type)
    ) {

View on GitHub (pinned to 69428b1f8b)

Solutions

Add providerOptions: { xai: { channels: [...] } } alongside multichannel: true.
Set multichannel to false (or omit it) if channel separation is not actually needed.
Consult the xAI transcription provider options schema for the expected channels shape (array of channel descriptors).

Example fix

// before
providerOptions: { xai: { multichannel: true } }

// after
providerOptions: { xai: { multichannel: true, channels: [{ name: 'agent' }, { name: 'caller' }] } }

Defensive patterns

Strategy: validation

Validate before calling

const xaiOpts = providerOptions?.xai as { multichannel?: boolean; channels?: unknown } | undefined;
if (xaiOpts?.multichannel === true && xaiOpts.channels == null) {
  throw new Error('providerOptions.xai.channels is required when multichannel is true');
}

Type guard

function hasValidMultichannelOptions(o: unknown): o is { multichannel: true; channels: unknown[] } {
  return typeof o === 'object' && o !== null &&
    (o as any).multichannel === true && Array.isArray((o as any).channels);
}

Try / catch

try {
  await model.doStream({ ...options, providerOptions });
} catch (e) {
  if (InvalidArgumentError.isInstance(e) && e.argument === 'providerOptions') {
    // fix options and retry once with channels included
  } else throw e;
}

Prevention

Define providerOptions with the exported xai transcription options type so missing fields surface in TypeScript.
Validate dependent options together in your config layer, not at the API boundary.
Document multichannel/channels as a paired option in your team's transcription wrapper.

When it happens

Trigger: Calling streamObject-style transcription via xai.transcriptionModel(...).doStream (or the transcribe API) with providerOptions: { xai: { multichannel: true } } and omitting providerOptions.xai.channels.

Common situations: Enabling multichannel transcription for meeting/stereo audio but forgetting the channel array; copying a config snippet that only shows multichannel; boolean flag toggled on by environment/config without the dependent option.

Related errors

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