BoundaryML/baml · error

OpenAI transcription field

Error message

OpenAI transcription field `{field}` must be a string

What it means

BAML builds an OpenAI transcription request from your BAML client config's properties map. A required transcription field (e.g. `model` or `input`) is present but is not a JSON string (it is a number, bool, object, etc.), so BAML rejects it before calling OpenAI. This validation exists because the OpenAI transcriptions API only accepts string values for these fields.

Solutions

  1. Quote the field value so it is a JSON string in the BAML client config (e.g. model "gpt-4o-transcribe").
  2. Check which required field is named in the error and ensure the properties map in your BAML client block defines it as a string.
  3. If the value comes from an expression or environment variable, coerce it to a string before interpolation.

Example fix

// before (BAML client properties)
model 4o-mini-transcribe

// after
model "gpt-4o-mini-transcribe"
Defensive patterns

Strategy: validation

Validate before calling

const required = ['model', 'input'];
for (const f of required) {
  const v = props[f];
  if (v !== undefined && typeof v !== 'string') {
    throw new Error(`Field "${f}" must be a string, got ${typeof v}`);
  }
}

Type guard

const isString = (v: unknown): v is string => typeof v === 'string';

Try / catch

try {
  await baml.transcribe(...);
} catch (e) {
  if (String(e).includes('must be a string')) {
    console.error('Check transcription client config: quote all field values');
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling a BAML client of provider openai/transcription where a required field in the client's properties (e.g. `model`) is set to a non-string literal such as a number, boolean, array, or nested object.

Common situations: Typos in BAML config where the value is unquoted (e.g. model 4o-mini-transcribe instead of "gpt-4o-mini-transcribe"), templating expressions that resolve to non-strings, or copy-pasted config from a non-transcription client.

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/4b055a115eb5d754. Report an issue: GitHub.

Appendix: source

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

}

fn reject_reserved_request_fields(properties: &BamlMap<String, Value>) -> Result<()> {
    for key in ["messages", "stream"] {
        if properties.contains_key(key) {
            bail!("OpenAI transcriptions do not support reserved request field `{key}`")
        }
    }
    Ok(())
}

fn required_string_field(properties: &BamlMap<String, Value>, field: &str) -> Result<String> {
    let value = properties
        .get(field)
        .with_context(|| format!("OpenAI transcriptions require string field `{field}`"))?;

    match value {
        Value::String(value) => Ok(value.clone()),
        _ => bail!("OpenAI transcription field `{field}` must be a string"),
    }
}

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

fn optional_response_format(
    properties: &BamlMap<String, Value>,
    model: &str,
) -> Result<Option<String>> {

View on GitHub (pinned to bd85ce9dee)