BoundaryML/baml · error

OpenAI transcription field `temperature` must be a number…

Error message

OpenAI transcription field `temperature` must be a number or string

What it means

optional_temperature validates that the transcription client's `temperature` property, when present, is either a JSON number or a string; other types (bool, array, object, null literal in a wrong form) are rejected. BAML passes it through as a string to the OpenAI transcriptions API, which itself accepts only 0..1.

Solutions

  1. Set temperature to a numeric literal (e.g. temperature 0.2) or a quoted string (temperature "0.2").
  2. Remove the temperature property to use the API default.
  3. Also ensure the value is within OpenAI's accepted range 0.0-1.0 for transcription models.

Example fix

// before
temperature true

// after
temperature 0.2
Defensive patterns

Strategy: validation

Validate before calling

if (props.temperature !== undefined) {
  const t = props.temperature;
  if (typeof t !== 'number' && typeof t !== 'string') {
    throw new Error('temperature must be a number or string');
  }
  const n = Number(t);
  if (Number.isNaN(n) || n < 0 || n > 1) {
    throw new Error('temperature must be between 0 and 1');
  }
}

Type guard

const isValidTemperature = (v: unknown): v is number | string =>
  typeof v === 'number' || typeof v === 'string';

Try / catch

try {
  await baml.transcribe(...);
} catch (e) {
  if (String(e).includes('temperature')) {
    console.error('Set temperature as a number (0.2) or quoted string ("0.2")');
  }
  throw e;
}

Prevention

When it happens

Trigger: Setting temperature in the BAML transcription client properties to a non-numeric, non-string JSON value such as true, [0.2], or {value: 0.2}.

Common situations: Boolean-looking config (temperature true), copying temperature from another provider's client that uses different typing, or templated values that resolve to objects.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/96d1069104b34941. Report an issue: GitHub.

Appendix: source

Thrown at engine/baml-runtime/src/internal/llm_client/primitive/openai/types.rs:210

                        model,
                        "gpt-4o-transcribe"
                            | "gpt-4o-mini-transcribe"
                            | "gpt-4o-mini-transcribe-2025-12-15"
                            | "gpt-4o-transcribe-diarize"
                    )) => Ok(Some(value.clone())),
        Some(Value::String(value)) => bail!(
            "OpenAI transcription response_format `{value}` is not supported by model `{model}` in BAML; use `json`"
        ),
        Some(_) => bail!("OpenAI transcription field `response_format` must be a string"),
        None => Ok(None),
    }
}

fn optional_temperature(properties: &BamlMap<String, Value>) -> Result<Option<String>> {
    match properties.get("temperature") {
        Some(Value::Number(value)) => Ok(Some(value.to_string())),
        Some(Value::String(value)) => Ok(Some(value.clone())),
        Some(_) => bail!("OpenAI transcription field `temperature` must be a number or string"),
        None => Ok(None),
    }
}

fn filename_for_mime(mime: &str) -> String {
    let subtype = mime
        .split('/')
        .next_back()
        .unwrap_or("mpeg")
        .split(';')
        .next()
        .unwrap_or("mpeg")
        .trim()
        .to_ascii_lowercase();
    let extension = match subtype.as_str() {
        "mpeg" | "mp3" | "x-mp3" => "mp3",
        "wav" | "wave" | "x-wav" | "vnd.wave" => "wav",
        "mp4" | "m4a" | "x-m4a" => "m4a",

View on GitHub (pinned to bd85ce9dee)