{"record":{"id":"4b88d9980f6290ee","repo":"BoundaryML/baml","slug":"bamlerror-bamlclienterror-bamlclientfinishreasonerror","errorCode":null,"errorMessage":"BamlError: BamlClientError: BamlClientFinishReasonError: {message}","messagePattern":"BamlError: BamlClientError: BamlClientFinishReasonError: (.+?)","errorType":"exception","errorClass":"BamlClientFinishReasonError","httpStatus":null,"severity":"error","filePath":"engine/language_client_typescript/src/errors.rs","lineNumber":169,"sourceCode":"    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())\n}\n\nfn throw_baml_client_finish_reason_error(\n    prompt: &str,\n    raw_output: &str,\n    message: &str,\n    finish_reason: Option<&str>,\n    detailed_message: Option<&str>,\n) -> napi::Error {\n    let error_json = serde_json::json!({\n        \"type\": \"BamlClientFinishReasonError\",\n        \"prompt\": prompt,\n        \"raw_output\": raw_output,\n        \"message\": format!(\"BamlError: BamlClientError: BamlClientFinishReasonError: {}\", message),\n        \"finish_reason\": finish_reason,\n        \"detailed_message\": detailed_message,\n    });\n    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())\n}\n\nfn throw_baml_client_http_error(\n    client_name: &str,\n    message: &str,\n    status_code: &ErrorCode,\n    detailed_message: Option<&str>,\n    raw_response: Option<&str>,\n) -> napi::Error {\n    let error_json = serde_json::json!({\n        \"type\": \"BamlClientHttpError\",\n        \"client_name\": client_name,\n        \"message\": format!(\"BamlError: BamlClientError: BamlClientHttpError: {}\", message),\n        \"status_code\": status_code.to_u16(),\n        \"detailed_message\": detailed_message,\n        \"raw_response\": raw_response,\n    });\n    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_typescript/src/errors.rs#L151-L187","documentation":"BamlClientFinishReasonError is thrown when the LLM response's finish reason indicates failure — typically the model stopped because it hit the max token limit instead of completing the output. The error JSON includes prompt, raw_output, finish_reason, and detailed_message.","triggerScenarios":"finish_reason is 'length' (or another non-success reason) on every retry, so the driver gives up and calls throw_baml_client_finish_reason_error from from_anyhow_error.","commonSituations":"max_tokens set too low for the requested output, long prompts consuming the context budget, or the model truncating large structured outputs.","solutions":["Increase max_tokens in the client options","Shorten the prompt or requested output size","Check finish_reason in the error payload to confirm truncation","Switch to a model with a larger context window"],"exampleFix":"// before\nclient GPT4 { provider openai options { model gpt-4 max_tokens 100 } }\n// after\nclient GPT4 { provider openai options { model gpt-4 max_tokens 4096 } }","handlingStrategy":"try-catch","validationCode":"// budget check before the call\nconst estimatedPromptTokens = Math.ceil(promptText.length / 4);\nif (estimatedPromptTokens + expectedOutputTokens > maxTokens) console.warn('Token budget may truncate output');","typeGuard":"const isFinishReasonError = (e: unknown): boolean => String(e).includes('BamlClientFinishReasonError');","tryCatchPattern":"try {\n  return await b.MyFunction(args);\n} catch (e) {\n  if (isFinishReasonError(e)) {\n    // finish_reason is 'length' — retry with more max_tokens or shorter output\n    return await b.MyFunction(args, { clientOverride: 'GPT4LargeBudget' });\n  }\n  throw e;\n}","preventionTips":["Set max_tokens generously relative to expected output size","Keep prompts lean to preserve output budget","Add a retry policy for finish-reason failures","Monitor finish_reason values in production telemetry"],"tags":["llm","finish-reason","token-limit","typescript"],"backgroundTag":"unexpected-response-shape","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}