For OpenCode's provider or model not found error, first match the selected model to the provider and model IDs that OpenCode actually loaded. The reference normally has the form providerId/modelId. A correct API key cannot repair a misspelled ID, an undeclared custom model or a configuration file that the running process never reads.
Follow the error, not just the phrase “provider problem”
| What you see | First branch to inspect |
|---|---|
ProviderModelNotFoundError | Provider/model identity, loaded catalog and model adapter |
| v2: model unavailable | Inactive provider, absent or disabled model, changed discovery or alias |
ProviderInitError | Provider package and initialization configuration |
| HTTP 401 or 403 from the endpoint | Credential, host and account permission |
| HTTP 429 or a billing message | The responding provider's rate and spending limits |
The official troubleshooting guide points model-not-found errors toward model references. In the provider source, lookup checks both the provider entry and its model map. The same error can also wrap an adapter's missing-model error. Capture the exact message before changing credentials or purchasing more credit.
1. Identify the version and the selected model
Run these checks from the project where the failure occurs. If the desktop application uses a different server, compare its version and configuration with this terminal installation:
opencode --version
opencode models
opencode auth listFind the full model reference in the list, then compare it character by character with your selection. The provider prefix is part of the identity. A model offered through a custom gateway does not become the built-in Anthropic provider merely because its name contains Claude.
Do not interpret a saved credential as proof of successful remote authentication. It establishes that a credential exists locally; the endpoint still has to accept it when a request is made.
2. Fix the provider/model pair
This example uses the v1 provider format and illustrates the three matching identifiers. Set the referenced environment variable in the process that launches OpenCode, or use the documented credential flow. Merge the relevant fields into your configuration rather than overwriting unrelated settings:
{
"$schema": "https://opencode.ai/config.json",
"model": "kunavo/claude-sonnet-4-6",
"provider": {
"kunavo": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kunavo",
"options": {
"baseURL": "https://api.kunavo.com/v1",
"apiKey": "{env:KUNAVO_API_KEY}"
},
"models": {
"claude-sonnet-4-6": {
"name": "Claude Sonnet 4.6"
}
}
}
}
}Here, kunavo is the provider key and claude-sonnet-4-6 is the model key. Therefore the selection is kunavo/claude-sonnet-4-6. Selecting anthropic/claude-sonnet-4-6 chooses a different provider; selecting Kunavo/Claude Sonnet 4.6 substitutes display names for lookup keys. Neither refers to the entry shown above.
When using /connect and Other for a custom provider, enter the same provider ID. The credential does not by itself define the model catalog. Check the adapter too: the v1 compatible adapter shown here uses Chat Completions; a Responses endpoint requires the appropriate adapter.
3. Keep v1 and v2 configuration separate
The v2 provider documentation uses providers, package and settings, instead of the v1 provider, npm and options. Use its version-specific setup rather than copying the preceding block into a v2 configuration unchanged.
In v2, a model's map key can also differ from the upstream modelID. If the map contains coder and sends upstream model upstream/coder-v2, choose company/coder for provider company. Changing the selection to the upstream name would bypass the configured alias.
4. Check which configuration wins
OpenCode merges configuration sources. A project file can override the global model; custom paths, inline configuration and managed settings can also matter. Inspect the failing project's file, the global configuration, and any configured overrides. Check provider allowlists or disabled-provider entries.
Make one targeted change, restart the affected process, and list models again. If the model is now available but its first request returns an HTTP error, follow that new error. Keep the original files and session data while diagnosing; deleting the whole data directory can remove credentials and history without fixing a wrong model reference.
Finish with a small request
Once the selection resolves, try one short prompt before a repository task. Confirm the intended provider receives it and records the expected model. If it still fails, collect the version, sanitized configuration, exact error and relevant log excerpt. Review logs for keys and project content before sharing them.
For Kunavo, continue with the OpenCode integration guide and check your usage record. The current Claude Sonnet 4.6 rate is $1.20 input and $6.00 output per million tokens. A price comparison becomes useful after the client is selecting the intended route.
FAQ
What does ProviderModelNotFoundError mean in OpenCode?
OpenCode cannot resolve the selected provider/model pair, or its model adapter cannot resolve that model. Check the loaded provider ID, model key and active configuration before treating it as a balance or API-key problem. A provider HTTP response such as 401 is a different diagnostic branch.
Why did adding my API key not add the custom model?
A saved credential and a provider/model definition serve different purposes. In the v1 custom-provider flow, the provider ID entered through /connect must match the configuration key, and the model must be declared in that provider's models map.
Should I use provider or providers in opencode.json?
Match your installed version's documentation. The v1 documentation uses provider with npm and options. The v2 documentation uses providers with package and settings. Mixing the two formats is not a reliable migration; follow the matching schema and provider guide.
Why does the model work in one project but not another?
Project settings can override global settings, while environment, inline or managed configuration can also affect the result. Check the selected model and provider settings from the failing project's working directory. If a desktop client connects to a different server, inspect that server's configuration too.
Official documentation and provider source checked September 17, 2026. The example explains configuration identity; it is not an end-to-end task benchmark.