I investigated the fallback model settings (fallbackModel) in Claude Code

Hello, I'm Tsukuboshi (tsukuboshi0755)!

When using Claude Code, requests can temporarily fail due to model overload. Especially when regularly using high-performance models like Opus, requests may not go through during periods of high traffic, forcing you to interrupt your work.

In this article, I'll introduce how to use Claude Code's fallbackModel setting to automatically switch to a different model when a model becomes unavailable!

What is fallbackModel?

fallbackModel is a feature that automatically switches to a different model when Claude Code's primary model becomes overloaded or unavailable, or when it returns a non-retryable server error.

The fallback applies only to the current turn.
Since the primary model is tried again on the next turn, if the temporary issue has been resolved, processing will continue with the primary model!

Conditions that trigger a fallback

A fallback is triggered under the following conditions.

• When the primary model is overloaded
• When the primary model is unavailable
• When a non-retryable server error occurs

Conditions that do not trigger a fallback

A fallback is NOT triggered for the following errors.
These are handled by normal retry processing or error handling.

• Authentication errors
• Billing errors
• Rate limit errors (HTTP 429)
• Request size errors
• Transport errors

How to configure

fallbackModel can be configured in two ways.

Configuring in settings.json (persistent)

Add the fallbackModel key to settings.json and specify the fallback models as an array.

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

This setting persists across sessions.

There are 5 locations where settings.json can be placed, with higher priority given to those listed first.

Note that fallbackModel is not merged across configuration files.
The setting from the highest-priority file is used as-is for the entire chain.

Configuring with a CLI flag (per session)

Using the --fallback-model flag, you can specify a fallback configuration that applies only to a single session.

claude --fallback-model sonnet,haiku

You can specify multiple models separated by commas, and fallback will be attempted in the specified order.
This flag takes precedence over the fallbackModel setting in settings.json.

Specifiable values

The following formats can be used for fallback models.

• Model names (e.g., claude-sonnet-5, claude-opus-4-8)
• Model aliases (opus, sonnet, haiku, fable, best, default)
• The special keyword default expands to the account's default model

Fallback chain constraints

The fallback chain has several constraints.

Maximum of 3 models

The chain can specify up to 3 models.
If 4 or more are specified, the extra entries are ignored.

Automatic deduplication

Duplicate models within the chain are automatically removed.

Integration with availableModels

If availableModels (available model restriction settings) is configured, models not included in availableModels are automatically excluded from the fallback chain.

Constraints during compaction

During context compaction (compression) processing, fallback will not occur to a model with a smaller context window than the primary model.
This is because switching to a model with a smaller context window during compaction could result in the inability to retain conversation history.

Differences from the API's fallbacks parameter

By the way, while Claude Code's fallbackModel setting and the Claude API's fallbacks parameter have similar names, their mechanisms are different.

The API's fallbacks parameter is a feature that automatically retries the same request with a different model when Claude Fable 5 refuses a request due to the safety classifier (stop_reason: "refusal").
On the other hand, Claude Code's fallbackModel is a fallback for when the model itself is unavailable, and serves a different purpose.

References

https://code.claude.com/docs/en/model-config

https://code.claude.com/docs/en/settings

https://code.claude.com/docs/en/cli-reference

Closing

This time, I introduced Claude Code's fallback model setting (fallbackModel).

By configuring fallbackModel, you can avoid interrupting your work even when the primary model is temporarily unavailable.
Since the fallback applies only to the current turn and automatically reverts to the original model once the primary model recovers, there's no need to worry about being locked into a fallback model.

For those who regularly use high-performance models like Opus, consider setting Sonnet or Haiku as fallback destinations to improve availability!

That's all from Tsukuboshi (tsukuboshi0755)!