Development

OpenCode Free Usage Limit Reached: Causes and Fixes

Asep Alazhari

OpenCode free usage limit reached means the free model quota is used up. Here is how to confirm it on v1 and v2, why v1 just hangs, and the fixes that worked.

OpenCode Free Usage Limit Reached: Causes and Fixes

Error: Free usage limit reached. Connect a provider or subscribe to OpenCode Go to keep going, or switch models.

That is OpenCode 2.3.0 telling you the free model quota is used up. It showed up for me with and without a project config, so it is not a config problem. You can connect a provider of your own, subscribe to OpenCode Go, or wait. I hit this on 2026-11-15 on both OpenCode 1.19.0 and 2.3.0, and v1 is the confusing one: opencode run prints nothing and hangs until you kill it.

Quick Fix

The free tier here means the free models OpenCode offers for a limited time, such as DeepSeek V4.1 Flash Free, according to the Console models docs. OpenCode Go is an optional subscription for coding models tested by the OpenCode team, according to the providers docs. I compared its price with other coding plans in my Xiaomi MiMo review.

Confirm that it is the quota first (the next sections show how), then pick one of these. OpenCode documents the first three. The last one is only my observation.

OptionWhat to doSource and status
Connect your own providerIn the TUI run /connect, choose the provider and enter its credentials, then run /models and pick one of its modelsOpenCode providers docs. A model from my own provider ran normally on 1.19.0 and 2.3.0 after the limit
Subscribe to OpenCode GoSubscribe in the OpenCode Console, copy the API key, run /connect, select OpenCode Go, paste the key, then run /models. The docs list Go at 10 dollars a month, Go Plus at 40 dollars a month, and Go Teams at 20 dollars per member a monthOpenCode Go docs. I did not test this
Add Console creditsAdd credits in the OpenCode Console. A processing fee of 4.6 percent plus 0.31 dollars is added to each purchaseConsole models docs. I did not test this
WaitNo reset time is documented. I saw no reset after about an hourMy own test, details below

Also Read: OpenCode YOLO Mode and Multi-Model CLI: Tested Guide

Which Free Tier Error Do You Have?

OpenCode’s maintainers collect free tier problems in issue #59387 and list six messages. They are not all the same problem, so match yours before changing anything.

MessageWhat it points toWhat to do
Free usage limit reached, or Free usage exceeded, subscribe to GoThe free allowance is used upThe Quick Fix table above
You've used today's free messages. They reset at ...The same limit, with a reset time. The issue notes that in some reports the reset never happensWait for the reset time, or use another provider
This version of OpenCode Desktop no longer supports free modelsThe desktop app is too old. The issue says the v1 desktop updater keeps you on 1.xDownload v2 from the OpenCode docs
OpenCode 1.18.0 or newer is required to use the free tierThe CLI version is too oldUpdate OpenCode
OpenCode's free tier can only be used from within OpenCodeFree models only work inside OpenCode, not through other clients, proxies, or direct API callsUse OpenCode itself, or another provider

The last message can also show up inside the official terminal app. A Windows reporter on v2.0.32 in issue #56324 had already upgraded, restarted, and logged in again with opencode auth login opencode, and still got it. That is a different error from the quota one, so a quota fix will not touch it.

Why OpenCode v1 Shows Nothing and Hangs

On v2 the quota error appears right away and the command exits with code 1. On 1.19.0 the same failure is invisible. opencode run "Run: npm run build" printed only its header line, > build · deepseek-v4.1-flash-free, and then waited until my 90 second timeout killed it with exit code 142.

The error is in the log, followed by a retry failure for the session title. Add --print-logs to see it on screen:

opencode run --print-logs -m opencode/deepseek-v4.1-flash-free "Run: npm run build"

This is the line it printed on 1.19.0, trimmed to the useful part:

level=ERROR message="stream error" providerID=opencode modelID=deepseek-v4.1-flash-free agent=build error.error="AI_APICallError: Free usage limit reached. Free models work in OpenCode (https://opencode.ai); subscribe to OpenCode Go to keep going: https://opencode.ai/go"

The session title request then fails with an AI_RetryError that says it failed after 3 attempts, with the same quota message as its last error. The OpenCode troubleshooting docs put the log at ~/.local/share/opencode/log/opencode.log, so you can also search it afterwards:

grep "Free usage limit" ~/.local/share/opencode/log/opencode.log

What I Observed on 1.19.0 and 2.3.0

I ran scripted opencode run calls on a throwaway project, with each version using its own data directory. Times are WIB, UTC plus 7, on 2026-11-15.

TimeVersionModelResult
15:15 to 15:161.19.0deepseek-v4.1-flash-free14 runs worked, each finishing in roughly 5 to 11 seconds
15:16:491.19.0deepseek-v4.1-flash-freeFirst limit error in the log. The next two runs hung until my 240 second timeout killed them
15:262.3.0deepseek-v4.1-flash-freeFirst limit error. 16 runs failed within 13 seconds, each printing the error
15:281.19.0mimo-v2.6-flash-freeSame limit error, so switching to another free model did not help
16:161.19.0deepseek-v4.1-flash-freeHeader line only, then a hang until the 90 second timeout. The log has the error
16:172.3.0deepseek-v4.1-flash-freeFailed instantly with exit code 1 and the error

Other runs had already used the free tier earlier that day, so I cannot tell you how large the quota is or how it is counted. What the table does show is that the limit is shared across free models, and that it was still active about an hour after the first error.

Does Updating to v2 Fix It?

Not for the quota message. Issue #59387 says most free tier reports come from v1 and that updating to v2 fixed this for many people. It also says v1 no longer supports free models. Both of my versions returned the same quota error, and my 1.19.0 runs worked until the quota ran out. For the version messages in the table above, updating may well help.

What Worked for Me

After the limit I switched the TUI to a model from my own provider, set up through 9Router, and it ran normally on both versions. The permission prompts behaved the same as before. I am not publishing my provider config here. The providers docs show the supported setup, including a custom OpenAI-compatible provider.

One thing I would not try: pointing another client or proxy at OpenCode’s free models. The issue says they only work inside OpenCode.

Also Read: DeepSeek V4 Flash Review (2026): What V4.1 Changed

What I Could Not Verify

  • The quota size, its time window, and when it resets. No source I found states it.
  • The limits and behavior of OpenCode Go beyond the plan prices in the docs.
  • Whether the limit is tied to my account, my IP address, or applies to everyone at once.
  • Whether opencode auth login opencode helps. The reporter in issue #56324 tried it and it did not.

How to Decide

If you see the quota message, do not debug your config. Run once with --print-logs to confirm it, then choose. If you need to keep working today, connect a provider you already have. If you want to stay on OpenCode’s own models, look at Go. If the message is about a version or about running inside OpenCode, it is a different problem and the table above tells you where to go next.

Back to Blog

Related Posts

View All Posts »