How to Configure Fallback Models in Claude Code

Claude Code can automatically try another model when the primary model is overloaded, unavailable, or returns another covered server error. For a single launch, use:

claude --fallback-model sonnet,haiku

For a persistent configuration, add an ordered array to your Claude Code settings:

{
  "fallbackModel": ["sonnet", "haiku"]
}

This is an availability mechanism, not a universal error handler. Authentication, billing, rate-limit, request-size, transport, and organization-policy failures keep their normal behavior rather than switching models.

What a Claude Code fallback chain does

A fallback chain tells Claude Code which models to try when the active model cannot accept a request for a covered availability reason. Claude Code attempts the entries in order and shows a notice when it switches.

The switch lasts for the current turn. On your next message, Claude Code tries the primary model again. This design lets a session survive a temporary capacity problem without permanently changing the model selected for the project.

Claude Code removes duplicate entries and uses at most three fallback models. A long list does not create unlimited retries.

Configure fallback models for one launch

Pass a comma-separated list to --fallback-model:

claude --model opus --fallback-model sonnet,haiku

In this example:

1. Claude Code starts with the configured Opus alias.
2. If the primary request hits a covered failure, it tries Sonnet.
3. If Sonnet also cannot accept it, it tries Haiku.
4. The next user message starts by trying the primary model again.

The flag applies to the Claude Code process you launch. It takes precedence over a fallbackModel value stored in settings.

Save fallback models in settings

Use an array, not a comma-separated string:

{
  "model": "opus",
  "fallbackModel": ["sonnet", "haiku"]
}

Each entry can be a supported model alias or a model name. Aliases are convenient when you want Claude Code to follow the current model assigned to that family. A complete model identifier is better when your application has been evaluated against one exact version and must remain pinned.

Do not put this configuration in CLAUDE.md. CLAUDE.md contains project instructions for the model; model selection and fallback behavior belong in Claude Code settings.

If you need help building project instructions, use the CLAUDE.md Generator. Keep operational settings and prompt instructions in their appropriate files.

Which errors trigger a fallback?

According to Anthropic's model configuration reference, availability fallback can cover:

• A primary model that is overloaded.
• A model that is unavailable or retired.
• Another non-retryable server failure covered by Claude Code.

The same documentation says these categories do not trigger the chain:

• Authentication errors.
• Billing errors.
• Rate-limit errors.
• Request-size errors.
• Transport errors.
• Organization policy denials.

Those failures require their own recovery. For example, changing models will not fix an expired credential, a spend cap, an invalid request body, or a blocked network connection.

Fallback models and 529 overload errors

A repeated 529 error is the clearest use case. Claude Code has already attempted its applicable automatic retries before showing the repeated-overload message. A fallback chain lets the same turn move to another model instead of ending immediately.

For the complete recovery flow across Desktop, CLI, and API integrations, read Claude Code Model Overloaded: How to Fix 529 Errors.

Choose a sensible fallback order

Order fallbacks by the requirement you are protecting.

Preserve capability first

For complex coding or reasoning tasks, choose the closest available model that can still satisfy the task. A very small model may be available but may not be an acceptable substitute for a difficult migration, security review, or architecture decision.

Preserve latency first

For interactive assistance, a faster model can keep the session moving during a brief overload. Review the result before accepting consequential changes.

Preserve cost first

For automated jobs, route to a model with known cost and output bounds. Record the model that completed each job so cost and quality measurements remain interpretable.

Preserve context-window requirements

Claude Code will not use a smaller-context fallback while compacting a conversation if doing so would cut off content that fits in the primary model's window. A chain that looks valid for normal turns can therefore be unavailable during compaction.

Use the FixTools Open Model Atlas to compare task fit, deployment requirements, context, and licensing before choosing alternatives for a broader application stack.

Fallback chains and model allowlists

An organization can restrict which models users may select. Claude Code drops fallback entries that are outside the effective availableModels allowlist.

If a chain never reaches a model you expected:

1. Check the permitted models for the environment.
2. Confirm the model alias resolves to a permitted and available version.
3. Remove retired or unreachable pinned model names.
4. Keep at least one fallback that the account can actually access.

Do not bypass an organization allowlist. Ask the administrator to approve an appropriate model or change the managed configuration.

Verify that fallback is working

Claude Code does not confirm the fallback chain at startup, and /status does not display it. The visible confirmation appears when a failure actually causes Claude Code to switch.

Use this checklist when the expected switch does not occur:

• Confirm the setting key is exactly fallbackModel.
• Confirm the saved value is an array.
• Check whether a --fallback-model flag is overriding the saved setting.
• Confirm the failure category supports fallback.
• Check model access and organization allowlists.
• Check whether compaction requires a context window larger than the fallback provides.
• Update Claude Code if the installed version predates the behavior you need.

Fallback models in subagents and background work

Current Claude Code documentation applies the configured chain to subagents as well. This is useful for long-running workflows because a temporary model outage does not have to terminate every delegated task.

Availability does not remove the need for safe job design. Persist progress, make side effects idempotent, and set a completion condition outside the model response. A fallback may finish the task with different latency, cost, or output characteristics.

When manual switching is better

Automatic fallback is not always appropriate. Use /model and choose manually when:

• The next model changes the acceptable risk level.
• You need to understand the cost before continuing.
• The task depends on an exact model evaluation.
• A context-window difference may remove important history.
• You want to reduce the task before moving to a smaller model.

The best fallback policy is explicit: decide which errors permit switching, which models are acceptable, and what verification is required afterward.

Sources and verification

This guide was verified on September 3, 2026 against Anthropic's Claude Code model configuration, Claude Code error reference, and Claude API errors.