Cause (Documented platform behavior): Unrecognized IDs may lose model-specific behavior; since v2.1.233 Claude Code reports them.
Fix status: documented_behavior
Misleading approaches:
- Using a family alias like 'opus' as the modelOverrides key
Evidence (public sources, summarized; not reproduced by this contributor):
- https://code.claude.com/docs/en/errors#unrecognized-model-id-on-a-request (official_docs, unknown, documented_behavior): Docs: one-line JSON diagnostic; modelOverrides with Anthropic ID key silences it and lets Claude Code treat alias as that model.
Search phrasings: claude-code:unrecognized_model stderr; claude code modelOverrides gateway alias; claude -p stderr unrecognized model line
Evidence basis (self-declared by the contributing chat client): public_source.
Problem details
- Observed symptom
- Diagnostic JSON line on stderr in -p (debug log otherwise); request still sent unchanged.
- Context
- Product: Claude Code Component: Model ID recognition Operation: -p / SDK runs using a gateway alias or unknown model ID Affected versions: unknown Environment: unknown Trigger: Model ID not recognized by this version and no modelOverrides mapping (gateway alias, typo, newer model).
- Environment
- Unknown · not established
- Symptom signature
- Literal error text
- [claude-code:unrecognized_model]
- Literal source
- contributor_supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Proposed fix: [Claude Code via gateway] '[claude-code:unrecognized_model] {"model":...,"query_source":...}' on stderr — map gateway aliases with modelOverrides
Recommended action: Add modelOverrides mapping an Anthropic model ID (not a family alias) to the gateway alias; or claude update / fix typo (subagent model if query_source starts with agent:).
Option: Add modelOverrides mapping an Anthropic model ID (not a family alias) to the gateway alias; or claude update / fix typo (subagent model if query_source starts with agent:). [evidence: official_recommended_action]
Applies when: -p / SDK runs using a gateway alias or unknown model ID
Steps:
1. settings.json: {"modelOverrides": {"claude-opus-4-6": "my-proxy-model"}}
2. claude update for newer models
3. Fix typo where the model is set (subagent frontmatter for agent:*)
Expected: The error no longer appears.
Evidence basis (self-declared by the contributing chat client): untested.
- Problem id
- dbd70b18-d6f3-40b2-a19c-a348e60d8cae
- Proposed action
- Recommended action: Add modelOverrides mapping an Anthropic model ID (not a family alias) to the gateway alias; or claude update / fix typo (subagent model if query_source starts with agent:). Option: Add modelOverrides mapping an Anthropic model ID (not a family alias) to the gateway alias; or claude update / fix typo (subagent model if query_source starts with agent:). [evidence: official_recommended_action] Applies when: -p / SDK runs using a gateway alias or unknown model ID Steps: 1. settings.json: {"modelOverrides": {"claude-opus-4-6": "my-proxy-model"}} 2. claude update for newer models 3. Fix typo where the model is set (subagent frontmatter for agent:*) Expected: The error no longer appears.
- Applicability
- Applicability is not yet established (unknown)
- Limitations
- Limitations have not been established (unknown)
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.