[DOCS] Third-party model docs omit background side-query fallback to the active main model
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/model-config
Section/Topic
ANTHROPIC_DEFAULT_HAIKU_MODEL, deprecated ANTHROPIC_SMALL_FAST_MODEL, and third-party deployment guidance for background functionality
Current Documentation
The docs currently say:
|ANTHROPIC_DEFAULT_HAIKU_MODEL| The model to use forhaiku, or background functionality | Note:ANTHROPIC_SMALL_FAST_MODELis deprecated in favor ofANTHROPIC_DEFAULT_HAIKU_MODEL.
They also describe separate primary and small/fast defaults for third-party providers without explaining the fallback behavior added in v2.1.141. For example:
Claude Code uses these default models when no pinning variables are set: | Model type | Default value | | Primary model |us.anthropic.claude-sonnet-4-5-20250929-v1:0| | Small/fast model |us.anthropic.claude-haiku-4-5-20251001-v1:0|
and:
For regional endpoints, ensure the primary model and small/fast model are supported in your selected region
What's Wrong or Missing?
The current docs explain that background functionality uses the Haiku/small-fast model slot, but they do not explain the behavior Claude Code now uses on Bedrock, Vertex AI, Microsoft Foundry, and gateway deployments when that separate Haiku model ID is unavailable and no explicit override is set.
In v2.1.141, background side-queries were changed to fall back to the active main-loop model instead of sending an unavailable Haiku model ID. Without that note, readers are left with an outdated mental model that background side-queries always require a separate available Haiku model configuration on those providers.
Suggested Improvement
Add a short note in the model configuration and third-party provider docs clarifying that:
Before:
Background functionality uses the Haiku/small-fast model slot.
After:
Background functionality prefers the Haiku/small-fast model slot (ANTHROPIC_DEFAULT_HAIKU_MODEL, or deprecatedANTHROPIC_SMALL_FAST_MODEL). On Bedrock, Vertex AI, Microsoft Foundry, and gateway deployments, if no separate override is set and the configured Haiku model ID is unavailable, Claude Code v2.1.141 and later fall back to the active main-loop model for those background side-queries. Administrators should still pinANTHROPIC_DEFAULT_HAIKU_MODELwhen they want a specific background model.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/model-config | Defines ANTHROPIC_DEFAULT_HAIKU_MODEL as the background-functionality model and deprecates ANTHROPIC_SMALL_FAST_MODEL |
| https://code.claude.com/docs/en/amazon-bedrock | Documents separate primary and small/fast defaults for Bedrock |
| https://code.claude.com/docs/en/google-vertex-ai | Documents separate primary and small/fast defaults and region support checks |
| https://code.claude.com/docs/en/microsoft-foundry | Tells admins to pin all three model families for Foundry deployments |
| https://code.claude.com/docs/en/third-party-integrations | Centralized third-party deployment guidance that points readers to the model pinning behavior |
Total scope: 5 pages affected
This is scoped to one root cause: third-party model documentation does not explain the v2.1.141 fallback from an unavailable background Haiku model to the active main-loop model.
3 Comments
Found 1 possible duplicate issue:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Issue #58868 Verification
Title: [DOCS] Third-party model docs omit background side-query fallback to the active main model
Issue Date: 2026-05-13
Verification Date: 2026-05-31
Status: RESOLVED
---
Issue Summary
This issue reports that the documentation for Bedrock, Vertex AI, Microsoft Foundry, and gateway deployments does not explain the v2.1.141 fallback behavior: background side-queries now fall back to the active main-loop model when the configured Haiku model ID is unavailable and no explicit override is set. The reporter requested a note explaining that background functionality prefers Haiku but falls back to the primary model on these providers.
---
Verification Results
Claim 1: The model-config docs describe
ANTHROPIC_DEFAULT_HAIKU_MODELfor background functionality but omit the fallback behaviorStatus: RESOLVED
At https://code.claude.com/docs/en/model-config, line 309, the environment variable table states:
This page delegates provider-specific behavior to the individual provider pages, which do cover the fallback.
Verdict: The model-config page links to provider pages that document the fallback. This is reasonable information architecture.
---
Claim 2: Bedrock docs omit fallback-to-primary behavior for background side-queries
Status: RESOLVED
At https://code.claude.com/docs/en/amazon-bedrock, lines 249-254, the default model table and accompanying text state:
The default table shows "Small/fast model | Same as primary model," and the explanatory text states Claude Code defaults this to the primary model because Haiku may not be available. This is the fallback behavior described.
Verdict: The Bedrock page already documents the default-to-primary fallback for background tasks.
---
Claim 3: Vertex AI docs omit fallback-to-primary behavior for background side-queries
Status: RESOLVED
At https://code.claude.com/docs/en/google-vertex-ai, lines 227-232, the default model table and accompanying text state:
Same pattern as Bedrock: the table and text clearly document the default-to-primary fallback.
Verdict: The Vertex AI page already documents the default-to-primary fallback for background tasks.
---
Claim 4: Microsoft Foundry docs omit fallback-to-primary behavior for background side-queries
Status: RESOLVED
At https://code.claude.com/docs/en/microsoft-foundry, line 166:
Verdict: The Foundry page already documents the default-to-primary fallback for background tasks.
---
Claim 5: Third-party integrations page omits the fallback behavior
Status: RESOLVED
At https://code.claude.com/docs/en/third-party-integrations, line 326, the guidance links to the individual provider pages for model configuration:
Verdict: This page delegates to the provider-specific pages, which already document the fallback.
---
Current State
| Claim | Status |
|-------|--------|
| model-config page omits fallback | RESOLVED |
| Bedrock docs omit fallback | RESOLVED |
| Vertex AI docs omit fallback | RESOLVED |
| Foundry docs omit fallback | RESOLVED |
| Third-party integrations omits fallback | RESOLVED |
---
Suggested Fix
N/A - issue has been resolved. Every affected provider page already documents that background tasks default to the primary model when Haiku is unavailable, using explicit language and default-model tables that show "Small/fast model | Same as primary model."
---
References
ANTHROPIC_DEFAULT_HAIKU_MODELfor background functionality; links to provider pages for specifics---
Conclusion & Recommendation
Primary Concern: The issue reports that third-party provider docs omit explanation of the v2.1.141 fallback from an unavailable background Haiku model to the active main-loop model.
Resolution Status: RESOLVED
Recommendation: CLOSE
All five affected pages already document that the small/fast model defaults to the primary model on Bedrock, Vertex AI, and Foundry, with the reason given (Haiku may not be available). The default-model tables explicitly show "Same as primary model" for the small/fast model role. Each page then explains how to override with
ANTHROPIC_DEFAULT_HAIKU_MODEL. The information the reporter requested is already present in the documentation.This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.