Troubleshooting
LSP not starting
Section titled “LSP not starting”Verify the language server itself is installed and on your PATH (for Go, that means gopls: run which gopls). OpenCode does not replace the Go toolchain or promise to install gopls for you. Install go and gopls first, then enable LSP in your config; it is off by default.
MCP server won’t connect
Section titled “MCP server won’t connect”Run the server command standalone in your terminal first (e.g. uvx postgres-mcp --connection-string ...) and check stderr for errors. Verify the transport type matches what you declared in opencode.json - a stdio server that expects HTTP, or vice versa, will hang silently. Check that the binary or runtime (uvx, npx, node) is on your PATH inside the environment OpenCode runs in.
/undo doesn’t revert files
Section titled “/undo doesn’t revert files”/undo restores file changes through OpenCode’s snapshots when snapshots are available. If snapshots are disabled, unavailable, or the result is unclear, use Git as the authoritative checkpoint: git diff to see what changed, then git stash or another deliberate Git recovery step. Commit early and often so you always have a clean checkpoint to return to.
Compaction loses critical context
Section titled “Compaction loses critical context”Before compacting, write key decisions and findings to disk - a DECISIONS.md, a comment in the code, or an AGENTS.md rule. Use the documented compaction settings (compaction.auto, compaction.prune, and compaction.reserved) to control when context is compacted and how much room is reserved. Anything that exists only in the conversation and nowhere on disk is at risk when the window compacts.
ask permission stalls headless runs
Section titled “ask permission stalls headless runs”In opencode run, opencode serve, or opencode attach with no human at the keyboard, an ask permission has no one to answer it. The approval can stall indefinitely. For headless and CI use, set every permission to explicit allow or deny - never leave ask in the map. The CLI’s --auto flag can approve permissions that are not explicitly denied, but a purpose-built agent with a deliberate permission map is the safer default.
Port 4096 already in use
Section titled “Port 4096 already in use”Check for another OpenCode instance already running (opencode serve or a TUI session with its background server). Use lsof -i :4096 or ss -tlnp | grep 4096 to find the process. Start your server on a different port with the --port flag: opencode serve --port 4097.