[DOCS] Error reference suggests `/model` and `--model` for SDK `model_not_found` errors

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/errors

Section/Topic

There's an issue with the selected model error remediation

Current Documentation

The docs currently say:

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to select a different one. What to do: Run /model to pick from models available to your account Use an alias such as sonnet or opus instead of a full versioned ID. Aliases track the latest release so they do not go stale. * If the wrong model keeps coming back, a stale ID is set somewhere. Check in priority order: the --model flag, the ANTHROPIC_MODEL environment variable, then the model field in .claude/settings.local.json, your project's .claude/settings.json, and ~/.claude/settings.json.

What's Wrong or Missing?

This remediation is written as if every model_not_found error happens in the interactive CLI, but the same error also appears in SDK-hosted sessions.

The Agent SDK docs show different model controls:

A. TypeScript SDK uses SDK options, not CLI flags

The TypeScript SDK reference documents options.model, fallbackModel, and applyFlagSettings({ model: ... }), and it defines model_not_found as an SDK error type.

B. Python SDK uses ClaudeAgentOptions and set_model()

The Python SDK reference documents model, fallback_model, and set_model() for changing the active model.

C. The current error guidance sends SDK users to the wrong fix

For SDK or other hosted surfaces, telling users to run /model or check a --model flag is inaccurate because those controls may not exist in that host. That leaves users with instructions that do not match the documented SDK APIs.

This is also inconsistent with the v2.1.160 changelog, which says Claude Code fixed model-not-found errors that were suggesting --model when running via the SDK or other hosts where the CLI flag does not apply.

Suggested Improvement

Replace the current one-size-fits-all remediation with host-aware guidance.

Before:

Run /model to pick from models available to your account Check in priority order: the --model flag, the ANTHROPIC_MODEL environment variable, then the model field...

After:

Select a different available model using the controls for the surface you are running: CLI: use /model, claude --model ..., ANTHROPIC_MODEL, or the model setting Agent SDK (TypeScript): set options.model, fallbackModel, or call applyFlagSettings({ model: ... }) Agent SDK (Python): set ClaudeAgentOptions(model=...), fallback_model, or call set_model() Desktop or other hosted surfaces: use that host's model picker or surface-specific model configuration instead of CLI-only flags

At minimum, the page should stop recommending --model as a universal fix and should link SDK readers to the Agent SDK model configuration APIs.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/errors | 541-553 | Primary selected model remediation tells users to run /model and inspect --model |
| https://code.claude.com/docs/en/troubleshooting | 17 | Routes model not found users to the generic error reference |

Cross-references:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-sdk/typescript | 432, 560-563, 992 | TypeScript SDK uses options.model / applyFlagSettings, and model_not_found is an SDK error type |
| https://code.claude.com/docs/en/agent-sdk/python | 456-477, 813-814 | Python SDK uses set_model(), model, and fallback_model instead of CLI flags |
| https://code.claude.com/docs/en/desktop | 651-665 | Desktop maps --model / ANTHROPIC_MODEL to the model dropdown rather than a CLI flag |
| https://code.claude.com/docs/en/changelog | 32 | v2.1.160 notes: "Fixed model-not-found errors suggesting --model when running via the SDK or other hosts where the CLI flag doesn't apply" |

Total scope: 2 pages affected, 4 supporting cross-references