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

Hello, this is Tsukuboshi (tsukuboshi0755)!

When using Claude Code, requests may 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 returns an overload, unavailable, or non-retryable server error.

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

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.
They 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 remains effective across sessions.

There are 5 locations for settings.json, with priority increasing from top to bottom.

Note that fallbackModel is not merged across configuration files.
The settings from the highest-priority file are 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

Multiple models can be specified separated by commas, and fallback is 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 a maximum of 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 (a setting that restricts available models) 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 models 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 the conversation history.

Differences from the API's fallbacks parameter

Although 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 rejects a request via 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 the use cases differ.

References

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

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

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

In closing

This time, I introduced the fallback model configuration (fallbackModel) for Claude Code.

By configuring fallbackModel, you can avoid interrupting your work even when the primary model is temporarily unavailable.
Especially if you regularly use high-performance models like Opus, setting Sonnet or Haiku as fallback destinations is recommended for improving availability.

Note that since the fallback applies only to the current turn, the model will automatically revert to the primary model once it recovers.
There is no need to worry about "being stuck on the fallback model."

That's all from Tsukuboshi (tsukuboshi0755)!