skip to content

What does Claude Code's --fallback-model flag do, which failures trigger it, and how long does a switch last?

level: seniorimportance: nice to knowfreq 4%

answer

  1. availability, not quota
  2. comma-separated, tried in order
  3. three models after deduplication
  4. one turn, then back to primary
  5. invisible until the notice

basics

~20 s

--fallback-model names backup models Claude Code tries in order when the primary is overloaded or unavailable. Rate-limit, authentication and billing errors never trigger it, and a switch lasts one turn before the primary is tried again.

solid answer

~40 s

`claude --fallback-model sonnet,haiku` gives a session a chain of backups, and the `fallbackModel` settings array persists one; the flag overrides the setting. When the primary is overloaded, unavailable or returns another non-retryable server error, Claude Code tries each entry in order and shows a notice. Authentication, billing, rate-limit, request-size and transport errors, and an organization policy denial, never trigger a switch. A switch lasts only for the current turn, so the next message tries the primary first. Chains are capped at three models after duplicates are removed, entries outside an `availableModels` list are dropped, and the chain also covers subagents without changing the session's model. Nothing confirms the chain at startup and `/status` does not show it.

code

json · 3 lines
json
{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

go deeper

for a junior

Know that --fallback-model names backup models for when the main one is overloaded or unavailable, and that the switch is announced with a notice.

for a middle

Explain the flag against the fallbackModel setting, the three-model cap, the one-turn lifetime, and the error classes that never trigger a switch.

for a senior

Separate availability fallback from classifier fallback when reading a notice, and account for compaction's window rule, allowlist filtering and subagents.

for a principal

Decide whether a team default chain is worth it: resilience during outages against cold-cache turns, surprise notices, and models that may sit outside policy.

## What a fallback chain is for A **fallback chain** is a list of backup models that Claude Code switches to when the primary model cannot serve a request, so the turn completes instead of failing. Without one, Claude Code retries the same model and then surfaces the server's error, and you retry or switch models yourself. It is an **availability** mechanism: it answers "the model is down or overloaded", not "I am out of quota" and not "the request was refused for its content". ## What triggers a switch and what does not | Triggers the chain | Never triggers the chain | |---|---| | primary model overloaded | authentication errors | | primary model unavailable, such as a retired model | billing errors | | another non-retryable server error | rate-limit errors | | Bedrock or Agent Platform refusing a model your account cannot invoke | request-size errors | | | transport errors | | | a denial by your organization's policy check | The rate-limit row is the one candidates most often get wrong. Running into your plan's limits is handled by the normal retry and error path, not by moving to a cheaper model. ## Configuring it 1. **For one session**: `claude --fallback-model sonnet,haiku`, a comma-separated list tried in order. 2. **For every session**: the `fallbackModel` setting, written as an array, for example `["claude-sonnet-5", "claude-haiku-4-5"]`. 3. **Precedence**: the flag overrides the setting. Each entry is a model name or alias, and `"default"` expands to the default model. Claude Code removes duplicates and then caps the chain at **three models**, ignoring anything beyond. ## How long a switch lasts and what it touches - **One turn.** The switch lasts for the current turn only; your next message tries the primary model first again. - **In order.** An entry that cannot be reached either, such as a retired model pinned in settings, fails over to the next one the same way. - **Filtered.** Entries not permitted by an `availableModels` allowlist are dropped when the chain is read. - **Compaction.** The chain also covers compaction, but Claude Code will not fall back to a model with a smaller context window than the primary's, since summarizing there would cut part of the conversation first; if every fallback is smaller, compaction shows the original error. - **Subagents.** When a subagent's request fails over, it continues on the model that accepted it, and the session's own model is unchanged. - **Cache.** A fallback turn runs with a cold prompt cache on the fallback model, which costs more than a cached turn. ## Invisible until it fires Claude Code does not confirm the chain at startup, and `/status` does not display it. The notice shown when a switch happens is the first visible sign that a chain is configured. Anyone rolling a chain out to a team should say so in the team's setup notes, or developers will be surprised by a notice naming a model they did not pick. ## Not the same as safety-classifier fallback Claude Code has a second, unrelated fallback. On the newest models, safety classifiers can flag a request, most often in cybersecurity or biology, and Claude Code re-runs it on a designated fallback model. That one differs in every way that matters: - it is triggered by **content**, not availability; - the session **continues on the fallback model** until you switch back with `/model`; - it is controlled by `switchModelsOnFlag`, which can make Claude Code pause and ask instead. Knowing which of the two produced a model-change notice tells you whether the next message will go back to your primary model on its own. ## A worked example A developer launches `claude --model opus --fallback-model sonnet,haiku` during a capacity incident: 1. A request to Opus returns an overloaded error. Claude Code shows a notice and retries the turn on Sonnet. 2. Had Sonnet also been unreachable, the same turn would have moved on to Haiku. 3. The turn finishes. The developer's next message goes to Opus first again, and only fails over if Opus is still overloaded. 4. Separately, the developer's plan hits its rate limit an hour later. The chain does nothing; the session shows the usual rate-limit handling, because quota errors are not availability errors.

  • During auto-compaction the primary is overloaded and the only fallback has a smaller context window. What happens?
    Claude Code skips that fallback for compaction, because summarizing on a model with a smaller window than the primary's would cut off part of the conversation first. If every fallback is smaller, compaction shows the original error and you can retry. Ordinary turns still use the chain as usual.
  • A session on Opus 5.5 shows a notice that it moved to another model after a flagged request. Will the next message go back to Opus 5.5?
    No. That notice comes from safety-classifier fallback, not the `--fallback-model` chain. After a classifier fallback the session continues on the fallback model until you switch back with `/model`. Setting `switchModelsOnFlag` to `false` makes Claude Code pause and ask, offering to switch or to edit the prompt and retry.

  • --fallback-model kicks in when you hit your plan's rate limit
  • After a fallback the session stays on the backup model for good
  • /status lists the configured fallback chain
  • A fallback chain can list as many models as you like
  • Fallback chains and classifier fallback are the same mechanism