OpenCode error
OpenCode: ConfigInvalidError
ConfigInvalidError
Config file at C:\Users\Usuario\opencode.json is invalid
↳ Unrecognized keys: "name", "description", "rules", "context", "notes"Status: By designLast verified 2 documented fixes3 sources
What it means
opencode.json failed schema validation. The error lists the keys OpenCode does not recognize.
Causes
- The config contains keys that are not part of OpenCode's config schema. A maintainer: "this is expected, seems like your config is invalid, the error message is pretty clear on what you should fix" (#7483).
- Pasting a JSON schema or other document in as the config. A maintainer asked: "are u just pasting a schema as a config? you dont want to do that".
How to fix it
- Fix 1.
Remove the keys named in the error. Validate against the official schema by adding $schema at the top of the file, as every example in the config docs does.
JSON{ "$schema": "https://opencode.ai/config.json" } - Fix 2.
v1.2.11 added ConfigInvalidError checks to server error handling (PR #14685).
More OpenCode errors
All 17 OpenCode errorsProviderModelNotFoundErrorStatus: By designProviderInitErrorStatus: WorkaroundAI_APICallErrorStatus: WorkaroundThis credential is only authorized for use with Claude Code and cannot be used for other API requests.Status: By designAI_APICallError: messages.13: `tool_use` ids were found without `tool_result` blocks immediately after: toolu_01CfJCsh21fK1pAXsXWYJYBA, toolu_01NoqnwsaxoK3AYM2FyrxmjN. Each `tool_use` block must have a corresponding `tool_result` block in the next message.Status: Fixed in releasemessages.3.content.0.type: Expected `thinking` or `redacted_thinking`, but found `tool_use`. When `thinking` is enabled, a final `assistant` message must start with a thinking block (preceeding the lastmost set of `tool_use` and `tool_result` blocks). We recommend you include thinking blocks from previous turns. To avoid this requirement, disable `thinking`.Status: WorkaroundError: Unexpected error, check log file at [user-home]/.local/share/opencode/log/2025-08-26T215857.log for more detailsStatus: WorkaroundAI_RetryError: Failed after 4 attempts. Last error: Too Many RequestsStatus: Workaround
Related reading
- OpenCode Hacked: What the Console Breach Means for Your API KeysOpenCode disclosed a breach of its Console that may have exposed provider keys. Who is affected, what to rotate today, and why hosted key gateways are the real risk.
- OpenCode 2: How to Upgrade From v1 Without Breaking Your SetupOpenCode 2 upgrade from v1: what the migration guide says breaks (plugins, server API, TUI config), what carries over, and a safe checklist before you switch.
- Run Your Coding Agent as an API: OpenCode Server on RailwayOpenCode server on Railway: run opencode serve in a container as a password-protected HTTP API with a persistent volume, reachable from any machine or webhook.
- Give Every Agent PR a Live Preview: Railway Environments for AI Pull RequestsRailway preview environments for agent pull requests: an isolated copy of your whole stack for every PR, so you verify agent changes by running them.
- GPT-6 Astra Release Guide: Benchmarks, $10/$50 Pricing, and How to Run It in Codex and OpenCodeGPT-6 Astra release guide: OpenAI's max-capability model, its $10/$50 pricing and 1.05M context, what the benchmarks do and do not say, and commands to try it.
- Put an AI Reviewer on Every Pull Request: A Webhook Build with OpenCode and RailwayBuild an AI pull request reviewer on Railway: a webhook service runs OpenCode headless on every PR diff and posts findings as a review, never touching the code.
FAQ
What does "ConfigInvalidError" mean in OpenCode?
opencode.json failed schema validation. The error lists the keys OpenCode does not recognize.
How do I fix "ConfigInvalidError"?
There are 2 documented fixes. Start with the first: Remove the keys named in the error. Validate against the official schema by adding $schema at the top of the file, as every example in the config docs does.
Is this OpenCode error fixed?
Status: By design. Expected behavior, not a bug. The documented fixes change the setup that triggers it. Affected versions: Any version that validates config (reported on Windows, Jan 2026).
Sources
Last verified against 3 sources: official docs, maintainer replies and release notes.
Newsletter
Fixes for the tools you use, weekly
One email per week. New coding agent releases, what broke, and how developers are working around it.