Audio format must be provided or determinable from media typ

Error message

Audio format must be provided or determinable from media type

What it means

GeneratedAudioFile's constructor determines an audio format either from an explicitly provided `format` or by deriving it from the response media (content) type. If neither yields a format, a plain Error('Audio format must be provided or determinable from media type') is thrown. The source even notes this should become a proper AI SDK error class.

Source

Thrown at packages/ai/src/generate-speech/generated-audio-file.ts:45

  }) {
    super({ data, mediaType });
    let format = 'mp3';

    // If format is not provided, try to determine it from the media type
    if (mediaType) {
      const mediaTypeParts = mediaType.split('/');

      if (mediaTypeParts.length === 2) {
        // Handle special cases for audio formats
        if (mediaType !== 'audio/mpeg') {
          format = mediaTypeParts[1];
        }
      }
    }

    if (!format) {
      // TODO this should be an AI SDK error
      throw new Error(
        'Audio format must be provided or determinable from media type',
      );
    }

    this.format = format;
  }
}

export class DefaultGeneratedAudioFileWithType extends DefaultGeneratedAudioFile {
  readonly type = 'audio';

  constructor(options: {
    data: string | Uint8Array;
    mediaType: string;
    format: string;
  }) {
    super(options);
  }

View on GitHub (pinned to 69428b1f8b)

Solutions

Pass an explicit `format` (e.g. 'mp3') when constructing GeneratedAudioFile
Make the custom provider return a proper audio Content-Type like 'audio/mpeg'
Map unknown media types to a known audio format before constructing the file

Example fix

// before
new GeneratedAudioFile({ data: bytes, mediaType: 'application/octet-stream' });
// after
new GeneratedAudioFile({ data: bytes, mediaType: 'audio/mpeg', format: 'mp3' });

Defensive patterns

Strategy: validation

Validate before calling

const AUDIO_TYPES = ['audio/mpeg','audio/wav','audio/aac','audio/opus','audio/flac'];
if (!format && !(mediaType && AUDIO_TYPES.includes(mediaType))) {
  throw new Error('Provide a format or a known audio media type');
}

Type guard

function hasDeterminableFormat(f?: string, mt?: string): boolean {
  return f != null || (mt?.startsWith('audio/') ?? false);
}

Try / catch

try {
  return new GeneratedAudioFile({ data, mediaType, format });
} catch (e) {
  if (e instanceof Error && e.message.includes('Audio format must be provided')) {
    return new GeneratedAudioFile({ data, mediaType: 'audio/mpeg', format: 'mp3' });
  }
  throw e;
}

Prevention

Always pass an explicit format when wrapping raw audio bytes
Ensure custom providers set audio Content-Type headers
Avoid proxies that strip response headers

When it happens

Trigger: Constructing GeneratedAudioFile manually with no `format` and no/unknown `mediaType` (e.g. 'application/octet-stream' or empty); wrapping raw bytes from a custom provider whose response lacks a Content-Type header.

Common situations: Custom/own provider implementations returning audio without a content-type header; proxies stripping headers; manual construction of GeneratedAudioFile in tests with only binary data.

Related errors

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