Skip to content
BENIBIX Learn

fallbackModel Option

Also known as fallback_model, Agent SDK fallback model, Claude Agent SDK fallbackModel

The option that names a spare model to use when the main one fails.

Think of it like

It is like a spare driver. If the first one gets sick, the spare one drives.

Example

An agent runs on a busy model that fails now and then. With a spare model set, those runs finish on the spare instead of failing.

Why it matters

An agent that stops halfway can leave work half done. A back-up model keeps it going.

Definition

fallbackModel is the Agent SDK option that names a model to use if the main model fails. You can give one model or a list split by commas, and the agent tries them in order. The run goes on with the next model instead of stopping with an error. In Python the same option is called fallback_model. It does the same job as the fallbackModel setting in Claude Code.

Example code

typescript
model: "opus", fallbackModel: "sonnet"
If Opus fails, carry on with Sonnet.
The spare model only runs when the main one fails.

Common mistake

Picking a back-up that cannot do the job. A small model may finish the run but do it badly.

Key takeaways

  1. 1
    Used on failure. Not by choice.
  2. 2
    One or a list. Split by commas.
  3. 3
    Same as the setting. fallbackModel in Claude Code.