Home / Blog / Pricing

Pricing

OpenCode "Model not found" error: why it happens and how to fix it

OpenCode shows "Model not found" or ProviderModelNotFoundError? Why the model ID fails, the subagent spawn bug, and the fixes in the docs and issues.

By Engineer Foodie Desk ✓ Sources checked Nov 8, 2026

8 min read

Error strings quoted from OpenCode GitHub issues #62337, #50698, #44799, #46011, #33043 and #36427 (all verified Nov 8, 2026). Model ID rules checked Nov 8, 2026 in OpenCode’s models, agents and config docs. Every source is listed at the bottom. No affiliate links on this page (how we work).

The exact error: Model not found

It shows up in a few shapes. The newest report, #62337 (opened Nov 6, 2026, v2.2.5, macOS; verified Nov 8, 2026), is the subagent version:

Subagent failed (sessionID: ses_...): Model not found

When OpenCode itself can’t resolve the ID, it names the model. From #50698 (verified Nov 8, 2026):

Model not found: litellm/us-gov.anthropic.claude-sonnet-5#medium

And the typed version, from #44799 (verified Nov 8, 2026):

ProviderModelNotFoundError: Model not found: nvidia/nemotron-3-ultra-550b-a55b. Did you mean: nvidia/nemotron-3-ultra-550b-a55b?

Yes, it suggests the exact ID you typed. Mostly harmless, as The Hitchhiker’s Guide would put it, but deeply annoying.

The one-line answer: either OpenCode can’t match your provider/model string to an enabled model, or OpenCode sent the request fine and the provider answered “Model not found.” The detail that tells them apart comes from the triage bot on #62337: “When OpenCode can’t find a model itself, the error always names it: Model not found: <provider>/model-a. Your error is a bare Model not found, so OpenCode accepted the model, sent the request, and the gateway answered with that error.”

Model named in the error = OpenCode’s lookup. Bare Model not found = the provider or gateway said no.

Common causes, per the docs and issues

1. The ID format is off

OpenCode’s models docs (verified Nov 8, 2026) spell the format out: “Model selectors use provider/model with an optional #variant”. Their examples are openai/gpt-6.1-sol, openai/gpt-6.1-sol#high and openrouter/anthropic/claude-sonnet-5.5#high. The rules table:

PartRule
ProviderEnds at the first /; cannot contain / or #
ModelMay contain additional /; cannot contain #
VariantFollows # when present
CasingCase-sensitive

Source: OpenCode models docs, verified Nov 8, 2026.

The same page adds: “Use catalog IDs rather than provider display names.” So a pretty name you saw in a menu is not necessarily the ID.

#44799 is the slash trap in action. An NVIDIA NIM model whose ID itself starts with nvidia/ failed as nvidia/nemotron-3-ultra-550b-a55b. The reporter wrote that the doubled full-key form nvidia/nvidia/nemotron-3-ultra-550b-a55b “resolves fine” (providerID nvidia + modelID nvidia/nemotron-3-ultra-550b-a55b). That matches the docs rule that the provider ends at the first /. The issue was filed on 1.18.20 and closed on Oct 11, 2026 with the OpenCode 1 cleanup (more on that below).

2. A bad or inherited #variant

The models docs warn: “Names such as low, high, and max are not available for every model, and an unknown variant produces a model-resolution error.”

#50698 (opened Sep 22, 2026 on 1.18.30) is titled “Subagent spawned via Task tool without its own variant inherits parent’s variant concatenated onto model ID (model#variant), causing “Model not found” errors”. The full error continued: “The configured model ID (litellm/us-gov.anthropic.claude-sonnet-5#medium) is invalid. Suggested valid alternatives: us-gov.anthropic.claude-sonnet-5, us-gov.anthropic.claude-opus-4-8, us-gov.anthropic.claude-opus-5.” Those are the reporter’s LiteLLM gateway IDs, not OpenCode catalog names.

3. The model isn’t enabled where you are

The models docs list availability rules: “The model must be enabled.” / “Its provider must be available in the current project.” / “Credentials and configuration from another project do not carry over automatically.” And the caveat: “Catalog data, credentials, and configuration are location-scoped. A model available in one project may be unavailable in another.”

This is your Home Alone moment. You’re Kevin running through the house checking every room, and the model is fine. It’s in the other project.

One related note from the same page: free models hidden by OPENCODE_DISABLE_FREE_MODELS fail differently. “explicitly selecting one fails with Model unavailable” — a different string from this one.

4. The provider or gateway rejects the name (bare Model not found)

This is #62337. A custom OpenAI-compatible provider listed model-a and model-b. The reporter wrote that “opencode run -m <provider>/model-a \"...\" fails immediately with the same bare Model not found, while opencode run -m <provider>/model-b succeeds.” The triage bot explained the mechanics: “With only a name in each entry, OpenCode sends the key itself (\"model\": \"model-a\") to <baseURL>/chat/completions. If the gateway knows the model under a different name (a prefix, a version suffix, different casing), or your key isn’t allowed to use it, you get exactly this result.”

The reporter later confirmed: “Root cause found on our side — this is provider-side, not an OpenCode bug.” Their debug log said the model “is not availble anymore”, while “the endpoint still serves model-a in its catalog/model listing … but the inference endpoint rejects requests for it.” Right planet in the catalog, wrong planet at the endpoint.

The hosted-service version is #46011 on Zen: Error from provider (Console): Upstream request failed: [NOT_FOUND] Model not found, inaccessible, and/or not deployed on kimi-k2.7-code, for about half of sessions per the title. A member closed it on Oct 20, 2026: “This was a temporary problem with the model’s upstream provider around the time it was reported, and there haven’t been new reports here since.” The reporter had “repointed our default to kimi-k2.6 as a workaround.”

#36427 (“Model not found gpt-5.6-luna”, closed completed Jul 11, 2026) is screenshot-only, with no cause written out.

5. The subagent spawn path

Subagents are where this bites most. #33043 (1.17.8) is titled “Subagent sessions created with model=undefined causing ProviderModelNotFoundError”, with the log line cause=Cause([Fail(ProviderModelNotFoundError)]) and deepseek/deepseek-v4-flash as the named model. It auto-closed on Aug 21, 2026 after 60 days of inactivity. #50698 is the inherited-variant subagent case. #62337 is the subagent case that turned out to be the gateway.

The #62337 bot also notes a separate pre-spawn check: “When the model passed to the subagent tool isn’t in OpenCode’s available models, the tool fails before spawning with Model \"<provider>/<id>\" is not available. Use the models tool….” Different wording again — so read your error line carefully.

How to fix OpenCode Model not found, in order

Each step names its source.

  1. Read the exact line. Named model (Model not found: provider/x) means OpenCode’s lookup failed; bare Model not found means the provider answered with it (#62337 triage, verified Nov 8, 2026).
  2. Check your ID against the models list. The docs say: “Pick an entry from /models instead of guessing its provider or model ID.” Match the provider/model rules and the casing exactly.
  3. Drop or fix the #variant. An unknown variant “produces a model-resolution error” (models docs). If a subagent inherited one, give it its own model line (step 5).
  4. Make sure the model is enabled in this project. Per the docs, credentials and configuration “do not carry over automatically” between projects.
  5. Set the subagent model explicitly. The agents docs (verified Nov 8, 2026) say: “A subagent uses its configured model, or inherits the parent session’s model when none is configured.” Their example agent file, .opencode/agents/reviewer.md:
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-5-5#high

The #62337 reporter’s earlier workaround was the same idea: “pin agents to a model that resolves (e.g. <provider>/model-b)”. 6. On a custom or compatible gateway, use the gateway’s real name. The docs say: “Use the server’s real model name, limits, input and output types, and tool support.” The #62337 bot’s check: list the gateway’s models with curl -s -H "Authorization: Bearer $KEY" https://<your-gateway>/v1/models, then call /v1/chat/completions with that model directly. “If the second call also returns Model not found, the gateway is rejecting that name. Either use the exact name from /v1/models as the key in your models block, or ask the gateway admins to enable model-a for your key.” Aliases work too: “A selector object uses model; a provider catalog entry uses modelID for the ID sent to the provider.” 7. Update OpenCode. #50698 and #44799 were closed on Oct 11, 2026 with: “OpenCode 2.0 is now out and development is focused on V2, so we’re closing issues filed against OpenCode 1. Please upgrade (opencode upgrade --major…)”. Version-gate questions live in OpenCode 1.18 required. 8. On Zen, switch model and wait it out. #46011 was a temporary upstream problem per the member who closed it; the reporter moved to kimi-k2.6 in the meantime. 9. Report it. If it still fails on 2.x, open an issue with your version, the exact error line and your model config. #62337 stays open as a request for clearer attribution; the bot wrote that “when an error comes from the provider, OpenCode should say so (for example, <provider> returned: Model not found (HTTP 404))”.

FAQ

Why does OpenCode say Model not found? Either your provider/model ID doesn’t match an enabled catalog entry, or OpenCode sent the request and the provider replied “Model not found” — the bare form means the latter, per #62337 (verified Nov 8, 2026).

How do I fix OpenCode Model not found for a subagent? Set model: provider/model in the subagent’s agent file; per OpenCode’s agents docs a subagent with no model inherits the parent session’s model (verified Nov 8, 2026).

What is ProviderModelNotFoundError in OpenCode? It’s the error type in #44799 and #33043 when OpenCode couldn’t resolve the configured model, such as a slash inside the model ID or a subagent spawned with model=undefined.

Does the #variant part cause Model not found? It can. OpenCode’s models docs say an unknown variant “produces a model-resolution error”, and #50698 shows a subagent inheriting the parent’s #medium.

Is Model not found the same as Model unavailable? No. The models docs say explicitly selecting a free model hidden by OPENCODE_DISABLE_FREE_MODELS “fails with Model unavailable”.

Here’s what I’d do

Look at the error first: named or bare. Named, I’d fix the ID against /models and kill any stray #variant. Bare, I’d stop editing OpenCode config and go poke the gateway with the /v1/models check, because #62337 shows the catalog can list a model the endpoint won’t serve. For subagents, I’d always write the model into the agent file rather than trusting inheritance.

If you’re on the free tier and the wall you hit is a quota rather than an ID, that’s OpenCode free usage exceeded. Wondering what costs money in the first place? See is OpenCode free. Weighing a switch? OpenCode vs Claude Code and AI coding tools compared have dated prices.

Sources

  1. OpenCode GitHub issue #62337 (subagent “Model not found” at spawn; open): https://github.com/anomalyco/opencode/issues/62337 (verified 2026-11-08)
  2. OpenCode GitHub issue #50698 (inherited #variant on subagents; closed not_planned Oct 11, 2026): https://github.com/anomalyco/opencode/issues/50698 (verified 2026-11-08)
  3. OpenCode GitHub issue #44799 (ProviderModelNotFoundError, slash in model ID; closed not_planned Oct 11, 2026): https://github.com/anomalyco/opencode/issues/44799 (verified 2026-11-08)
  4. OpenCode GitHub issue #46011 (Zen kimi-k2.7-code [NOT_FOUND] Model not found; closed not_planned Oct 20, 2026): https://github.com/anomalyco/opencode/issues/46011 (verified 2026-11-08)
  5. OpenCode GitHub issue #33043 (subagent model=undefined, ProviderModelNotFoundError; auto-closed Aug 21, 2026): https://github.com/anomalyco/opencode/issues/33043 (verified 2026-11-08)
  6. OpenCode GitHub issue #36427 (“Model not found gpt-5.6-luna”; closed completed Jul 11, 2026): https://github.com/anomalyco/opencode/issues/36427 (verified 2026-11-08)
  7. OpenCode models docs (ID format, rules, availability, variants, aliases): https://opencode.ai/v2/docs/models (verified 2026-11-08)
  8. OpenCode agents docs (subagent model, inheritance): https://opencode.ai/v2/docs/agents (verified 2026-11-08)
  9. OpenCode config docs (default model format): https://opencode.ai/v2/docs/config (verified 2026-11-08)

Related reading