[DOCS] Inconsistency between `--fallback-model` flag restrictions and "Max User" fallback behavior

[coygeek]

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/cli-reference - https://code.claude.com/docs/en/costs - https://code.claude.com/docs/en/model-config

Section/Topic

The usage requirements for automatic model fallback, specifically distinguishing between the --fallback-model CLI flag and the built-in fallback behavior for Max/Pro subscribers.

Current Documentation

From CLI Reference:

--fallback-model | Enable automatic fallback to specified model when default model is overloaded (print mode only)

From Manage costs effectively:

For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus.

From Model configuration (default model setting):

For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus.

What's Wrong or Missing?

There is a contradiction regarding whether model fallback is restricted to "print mode" (non-interactive).

1. The CLI Reference explicitly labels the --fallback-model flag as "(print mode only)."
2. The Costs and Model Configuration pages describe a fallback from Opus to Sonnet for Max users as a general feature, implying it works in standard interactive sessions.

It is unclear if the "Max user" fallback is a separate internal mechanism that does work in interactive mode, or if all forms of model fallback are strictly limited to print mode. If the latter is true, interactive users hitting a threshold or encountering an overloaded model might be confused when an automatic fallback does not occur.

Suggested Improvement

Clarify the scope of fallback behavior in the Costs and Model Config sections.

Suggested addition to Manage costs effectively:

"For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus. Note: In interactive mode, this fallback occurs [automatically/only after a prompt]; for automated scripts using the CLI, use the --fallback-model flag (available in print mode only)."

Alternatively, if the Max user fallback only works in print mode, the Costs section should be updated to say:

"For certain Max users running in print mode (-p), Claude Code will automatically fall back to Sonnet..."

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation: CLI Reference
• Related documentation: Model Configuration

[coygeek]

What’s FIXED

After reviewing the current documentation, I have found that no updates have been made to address the confusion regarding model fallback behavior. The specific sections identified in the original report remain unchanged:

• CLI Reference: At https://code.claude.com/docs/en/cli-reference, the entry for the --fallback-model flag still explicitly states it is for "(print mode only)" and provides the example claude -p --fallback-model sonnet "query".
• Costs: At https://code.claude.com/docs/en/costs, the documentation still states, "For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus," without specifying if this is also restricted to print mode.
• Model Config: At https://code.claude.com/docs/en/model-config, the default model setting section repeats the same threshold-based fallback description for Max users without clarifying the operational mode.

What’s UNRESOLVED

The central contradiction remains unaddressed. There is still a lack of technical precision regarding the two different types of fallback:

1. Overload-based Fallback: The --fallback-model flag is documented at https://code.claude.com/docs/en/cli-reference as restricted to non-interactive "print mode" (-p). There is no explanation as to why this behavior is unavailable in interactive mode.
2. Threshold-based Fallback: The documentation at https://code.claude.com/docs/en/costs describes a fallback from Opus to Sonnet for Max users as a general feature. It remains unclear if this internal mechanism functions in standard interactive sessions or if it, too, is restricted to print mode.

My original request for a clarifying note—explaining whether interactive users should expect an automatic fallback or if they must manually switch models when hitting limits—has not been implemented.

Conclusion

I am keeping this issue open. The documentation still presents a conflicting view of a high-impact feature. To satisfy this request, the documentation at https://code.claude.com/docs/en/costs or https://code.claude.com/docs/en/model-config must be updated to clarify whether threshold-based model fallbacks for subscription users are supported in interactive mode, or if all fallback logic is strictly reserved for the non-interactive CLI.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

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.