BoundaryML/baml · error · BamlTimeoutError

BamlError: BamlClientError: BamlTimeoutError: {message}

Error message

BamlError: BamlClientError: BamlTimeoutError: {message}

What it means

BamlTimeoutError is thrown by throw_baml_timeout_error when the LLM client exceeds its configured timeout. The error JSON includes client_name and message; the timeout is per-client in the BAML config.

Source

Thrown at engine/language_client_typescript/src/errors.rs:204

    });
    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())
}

fn throw_baml_abort_error(detailed_message: Option<&str>) -> napi::Error {
    let error_json = serde_json::json!({
        "type": "BamlAbortError",
        "detailed_message": detailed_message,
    });
    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())
}

fn throw_baml_timeout_error(client_name: &str, message: &str) -> napi::Error {
    let error_json = serde_json::json!({
        "type": "BamlTimeoutError",
        "client_name": client_name,
        "message": format!("BamlError: BamlClientError: BamlTimeoutError: {}", message),
    });
    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Increase the timeout in the client options (e.g. timeout 120s)
2. Check provider status / network latency for the affected client
3. Reduce output size (max_tokens, prompt length) to shorten request duration
4. Add a retry policy so timeouts trigger a fresh attempt

Example fix

// before
client GPT4 { provider openai options { model gpt-4 timeout 10s } }
// after
client GPT4 { provider openai options { model gpt-4 timeout 120s } retry_policy Exponential }

// ensure a sane timeout is configured before long calls
if (clientConfig.timeoutMs && clientConfig.timeoutMs < expectedDurationMs) console.warn('BAML client timeout likely too small');

const isBamlTimeoutError = (e: unknown): boolean => String(e).includes('BamlTimeoutError');

try {
  return await b.MyFunction(args);
} catch (e) {
  if (isBamlTimeoutError(e)) {
    await sleep(1000);
    return await b.MyFunction(args); // retry once on timeout
  }
  throw e;
}

When it happens

Trigger: A provider request exceeds the client's timeout setting in baml_src; slow streaming, hung connections, or an unreasonably small timeout value.

Common situations: Long generations with large max_tokens, provider latency spikes, corporate proxies adding latency, or a default timeout too low for heavy workloads.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• LLM client "{client_name}" timed out: {message}
• ExposedError::TimeoutError { client_name, message }
• timeout: {message}
• {self}\n\nDetailed message: {detailed_message}
• {}

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