Troubleshooting
Limits reached & quota errors
What each Contral limit message means and what to do when you hit a daily or monthly quota.
Use this page when Contral says you've reached a limit or quota. Each limit resets on its own schedule, and the rest of Contral keeps working while one feature is paused.
Check your current Contral usage#
- Dashboard: contral.ai/overview → Today's Usage shows the exact counters the server enforces.
- Editor: type
/usageto refresh your quota, or/statusto see your account and plan.
Daily limits reset at 00:00 UTC; monthly limits reset on the 1st of the month at 00:00 UTC. Full table: Usage limits & quotas explained.
Limit messages and what to do#
| Message | Limit | What to do |
|---|---|---|
| Daily message limit reached ({used}/{limit}). Upgrade to Pro for 250 messages/day, or Pro+ for unlimited. | AI messages per day | Wait until 00:00 UTC, switch to a BYOK model, or upgrade. |
| You've used your 3 free builds. Sign in for 25 free messages every day. | Trial builds without an account | Sign in or create a free account. |
| BYOK message limit reached ({used}/{limit}). The cap exists to prevent runaway loops; resets tomorrow. | Free plan BYOK messages (30/day) | Wait until 00:00 UTC, or upgrade for unlimited BYOK. |
| You've used this period's explanations. Upgrade, or wait for the reset. | Code explanations or auto-teach cards | Wait for the daily reset, or upgrade. |
Tier limit reached for teach. Use Contral: Upgrade plan to unlock. | Explanations in VS Code Chat (@contral) | Same as above. |
| Codebase analysis limit reached ({used}/{limit}). Upgrade to Pro for more. | Codebase analyses | Wait for the monthly reset (Free: 1 in total), or upgrade. /map still works. |
| Recursive mode is limited to 1 run per day on the Free plan. | Recursive runs | Use Fast mode, wait until 00:00 UTC, or upgrade. |
| Plan mode is a Pro feature… / Deep mode is a Pro feature… | Agent modes on Free | Use Fast mode, or upgrade. |
| Monthly web search quota reached… | Extension web searches | Wait for the 1st of the month, or upgrade. |
| Contral IDE won't create a new chat session | Sessions | Continue in an existing session, or upgrade. |
Limits and the AppSumo lifetime deal#
On an AppSumo tier, you can't buy a monthly plan to raise limits. Instead:
- Upgrade to a higher AppSumo tier at appsumo.com/account/products. See Upgrade or change your tier.
- Or keep working with your own API key. BYOK messages are unlimited on every AppSumo tier and don't use your AI messages.
You hit a limit sooner than expected#
- Recursive mode uses one AI message and one recursive run per turn.
- Auto-teach cards are created for every AI edit burst, including edits by Cursor, Copilot and other agents running in the background. If you don't need them all, turn off
contral.teachOnChangewhile you work. - Other devices count too. Limits are per account, so usage on your other computers and editors adds up.
- Daily resets follow UTC, not your local midnight.
- Monthly resets follow the calendar month, not your purchase date.
Your plan looks wrong, so limits look wrong#
If you're on a paid plan or AppSumo tier but get Free-plan limit messages (for example "Upgrade to Pro for 250 messages/day"):
- Run
/statusand check the editor is signed in with the account that has your plan. - Check the badge on contral.ai/overview for that account.
- If the dashboard shows Free, your license or subscription isn't on this account. AppSumo buyers: see Redemption errors. Subscribers: check Dashboard → Subscription.
- If the dashboard shows the right plan but the editor doesn't, sign out and back in to the editor.
"Could not reach the Contral usage server"#
Every counted action is checked with Contral's servers first, so Contral needs a connection to work. Messages like "Could not reach the Contral usage server… usage must be tracked server-side" or "Could not reach Contral to check usage" mean a network problem, not a limit. See Model & response errors.
Still stuck? Ask the support assistant in the corner of this page, or open a support ticket.