# fallbackModel Option

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

**Field:** Artificial Intelligence  
**Category:** Claude Agent SDK  
**Also known as:** fallback_model, Agent SDK fallback model, Claude Agent SDK fallbackModel

## Think of it like

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

## 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

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.

## Example code

```typescript
model: "opus", fallbackModel: "sonnet"
```

If Opus fails, carry on with Sonnet.

## Why it matters

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

## Common mistake

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

## Three principles

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

## Related terms

- [model Option](https://learn.benibix.com/term/ai/model-option)
- [fallbackModel](https://learn.benibix.com/term/ai/fallback-model-setting)
- [--fallback-model Flag](https://learn.benibix.com/term/ai/fallback-model-flag)
- [Model Fallback](https://learn.benibix.com/term/development/model-fallback)
- [ClaudeAgentOptions](https://learn.benibix.com/term/ai/claude-agent-options)

![Your agent sends a request to the model named in model, Opus, which is tried first. A dashed arrow, marked only if it fails, leads to the model named in fallbackModel, Sonnet. Both paths lead to the same end: the run goes on with no error for the user.](https://learn.benibix.com/diagrams/ai9-sdk-fallback.svg)

---

Source: https://learn.benibix.com/term/ai/fallback-model-option
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-20
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
