Engineering · OpenCode · Debugging
OpenCode model not found: why new models fail, and the fix
OpenCode model not found on a model OpenRouter lists? OpenCode 1.x froze its bundled models.dev catalog. Why it happens, how we fixed it, and how you can.
On this page
You pick a model that OpenRouter clearly serves, OpenCode starts, and the first prompt dies with this:
ProviderModelNotFoundError: Model not found: openrouter/google/gemini-3.7-flash.
Did you mean: google/gemini-2.5-flash, google/gemini-2.5-flash-image, ...If you're on OpenCode 1.x, the model is probably newer than the catalog your OpenCode process loaded. OpenCode builds its model list once, from a cache file or from a snapshot frozen into the release, and doesn't look again. Fixes first, then how we found it.
OpenCode model not found: the fixes
1. Restart OpenCode after its cache has refreshed. OpenCode 1.x refreshes the models.dev catalog in the background and writes it to disk, but the running process never re-reads it. A second start picks it up. On a laptop this is usually all you need.
2. Warm the cache before OpenCode starts. In a fresh container or CI job there is no cache, so OpenCode falls back to the snapshot bundled at its build time. Fetch the current catalog first. This is the command we ran in every sandbox:
mkdir -p ~/.cache/opencode && \
(curl -sfL --max-time 10 -z ~/.cache/opencode/models.json \
-o ~/.cache/opencode/models.json.new https://models.dev/api.json 2>/dev/null \
&& [ -s ~/.cache/opencode/models.json.new ] \
&& mv -f ~/.cache/opencode/models.json.new ~/.cache/opencode/models.json; \
rm -f ~/.cache/opencode/models.json.new; true)3. Declare the model in config. OpenCode extends its model database from opencode.json, even for ids models.dev doesn't list:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"openrouter": {
"models": {
"google/gemini-3.7-flash": {
"name": "Gemini 3.7 Flash"
}
}
}
}
}Add a limit with the model's real context and output too. A limit.context of 0 turns OpenCode's overflow detection and compaction off for that model, which you probably don't want.
4. Move to OpenCode 2. It refreshes the catalog from models.dev at boot. In our test a fresh opencode serve on 2.0.26 listed a model newer than its bundled snapshot 1.8 seconds after start.
5. Check the model still exists. Same error, different cause; more on that below.
OpenCode 1.x builds its model list once
The code is short once you find it. In OpenCode 1.18.7, packages/core/src/models-dev.ts fills the catalog once per process: the disk cache at ~/.cache/opencode/models.json if there is one, otherwise the models.dev snapshot bundled into that build. A background refresh then fetches models.dev, writes the cache, and invalidates the getter.
The catch is in provider.ts. It builds its Provider database once and never listens for that refresh. So the refresh does its job, the file on disk is current, and the process that wrote it keeps resolving model ids against whatever it loaded at start. Any model models.dev added after that point is "not found" until the process restarts.
On a developer's machine this almost never shows. The cache file exists from the last run, it's at most one restart stale, and people restart OpenCode all the time.
Why it only hit our sandboxes
Every UseAgent thread gets a fresh Linux sandbox, and OpenCode starts there for the first time. No cache file. So every OpenCode process we ran lived on the snapshot frozen into the 1.18.7 release, however old that was.
We found it on September 16 during a model sweep on one thread. Four models failed with ProviderModelNotFoundError while OpenRouter served them and the live models.dev listed them:
nex-agi/nex-n2.5-mini:freedots-studio/dots-3-note-preview:freeinclusionai/ling-3.0-flash-vl:freegoogle/gemini-3.7-flash
The "Did you mean" list offered older siblings from the same families (gemini-2.5-flash for gemini-3.7-flash, ling-3.0-flash for ling-3.0-flash-vl), which fits a catalog that predates the model.
The warm step we shipped, and later deleted
The fix went out that night. Before OpenCode's config is written and the process starts, the sandbox fetches models.dev into OpenCode's cache file, which is the command in fix 2. A few details that mattered:
curl -zmakes it conditional on the file's date, so a sandbox that already has a current cache doesn't download an unchanged catalog again.- It writes to a
.newfile and only moves it into place if the download is non-empty. A half-written catalog is worse than a stale one. - Ten-second cap, and it can never fail the run. If models.dev is down, OpenCode falls back to its snapshot exactly as before.
One limit we accepted: a sandbox that was already running OpenCode kept its old catalog until that process restarted. Warming the file doesn't help a process that has already read it.
OpenCode 2 has run in our sandboxes since early October, and on October 11 we deleted the warm step. OpenCode 2 keeps the catalog in its own keyed cache, never reads ~/.cache/opencode/models.json, and starts a models.dev refresh at boot that does invalidate what it serves. The step was now a models.dev fetch of up to ten seconds that nothing read. Our runtime does still wait for OpenCode 2's catalog to load on a cold start, up to 20 seconds, but that's for an empty catalog, not a stale one.
Config-declared models fix the other half
The catalog can be wrong in the other direction too: it knows the model but has the wrong numbers for your setup. models.dev gives every Anthropic model except Claude Haiku 4.5 an output limit of 128,000 tokens, and OpenCode 2.0.26 asks for all of it on its main calls. Our gateway caps a request at 65,536, so the first OpenCode run on our Opus credit was refused before anything left the gateway. We now declare each Anthropic model in the sandbox's opencode.json with its real context and a lower output limit, and OpenCode takes that limit whole, on top of its catalog entry:
"anthropic": {
"models": {
"claude-opus-5-5": { "limit": { "context": 1000000, "output": 64000 } },
"claude-haiku-4-5": { "limit": { "context": 200000, "output": 64000 } }
}
}The same lever adds a provider OpenCode has never heard of. Our GLM 5.3 route is declared entirely in config, with @ai-sdk/openai-compatible as the adapter and the model's limits next to it, so it runs no matter what the bundled catalog contains. The output-limit story from the Claude Code side is in how to run Claude Code in the cloud.
Sometimes the model really is gone
Two weeks later the same error came back on production, on nex-agi/nex-n2.5-mini:free, and this time the catalog was innocent. OpenRouter had retired three of the eight free models our picker offered: ling-3.0-flash-vl:free, nex-n2.5-mini:free and nex-n2.5-pro:free. Our list of free models had stopped updating after we turned off the job that probes new ones, so the picker kept offering models that no longer existed.
Two of those, ling-3.0-flash-vl:free and nex-n2.5-mini:free, had failed in September because our catalog was too old, and failed in October because the models were gone. Same models, same error text, opposite causes.
So before warming caches, check which case you're in:
# Is it in the current models.dev catalog?
curl -s https://models.dev/api.json | jq '.openrouter.models | has("google/gemini-3.7-flash")'
# Does OpenRouter still serve it?
curl -s https://openrouter.ai/api/v1/models | jq -r '.data[].id' | grep -x 'google/gemini-3.7-flash'If models.dev and the provider both list it, your OpenCode process has an old catalog. If the provider doesn't, no cache will help. For our side we added an hourly job that reads OpenRouter's public catalog and removes free models it no longer lists. It only ever removes; a model gets added back only after a real probe run passes. A failed or empty catalog read changes nothing, so an OpenRouter outage can't wipe the list.
Not every OpenCode failure is the model
While chasing this we hit a failure that looked related and wasn't: "The provider runtime POST request failed (HTTP 500)" on a Cerebras model. No request had reached OpenCode or the gateway. Our own runtime had refused a stale session-stop command left over from the turn before, and the 500 hid the reason. The same release made those refusals carry the runtime's actual reason. If your error doesn't say ProviderModelNotFoundError, read the OpenCode log before blaming the catalog; on Linux, OpenCode 1.x writes it to ~/.local/share/opencode/log/opencode.log.
UseAgent runs OpenCode 2 in every sandbox now, with your OpenAI, Anthropic, OpenRouter or Cerebras key behind our gateway. Try a model in a thread, or read the config code in the repo.
Frequently asked questions
Why does OpenCode say Model not found when OpenRouter lists the model?
OpenCode 1.x resolves model ids against the catalog it loaded when the process started: its cached models.dev file, or the snapshot bundled into that OpenCode build. A model added to models.dev later is unknown to that process until it restarts with a fresh cache.
Where does OpenCode cache its model list?
OpenCode 1.x reads ~/.cache/opencode/models.json on Linux. Writing a current copy of https://models.dev/api.json there before OpenCode starts makes new models resolve. OpenCode 2 keeps its catalog in its own cache and refreshes it from models.dev at boot.
Can I use a model that models.dev doesn't list at all?
Yes. Declare it under provider.