Quando algo quebra,
olhe aqui primeiro.
Diagnóstico em camadas: logs, dados locais, config resolvida, plugins, cache. Esta página segue a ordem que resolve mais rápido — e termina nos erros conhecidos.
01Logs e dados
mvcode --print-logs --log-level DEBUG # config final com todas as fontes mescladas mvcode debug config # caminho do banco local mvcode db path
Instalações migradas do opencode podem ter dados no diretório legado — a migração para maxvision-code acontece na primeira execução.
02A escada de diagnóstico
- Atualizeterminal
mvcode upgrade - Isole plugins
Rode
mvcode --pure. Resolveu? Reabilite plugins um a um — cheque a chavepluginda config global e os diretóriosplugins/. - Limpe o cache
Pacotes de provedor são instalados dinamicamente e cacheados. Cache corrompido causa
AI_APICallError:terminalrm -rf ~/.cache/opencode - Última instância: reset de dados
Config inválida persistente (
ProviderInitError)? Apague o diretório de dados e reconecte com/connect. Você perde sessões locais — exporte antes se importarem.
03Erros conhecidos
ProviderModelNotFoundError
Referência de modelo errada. O formato é provider/model — ex.: openai/gpt-5.2, openrouter/google/gemini-3-pro. Liste o que você tem com mvcode models.
ProviderInitError
Config de provedor inválida ou corrompida. Revise a seção provider contra provedores; persistindo, reset de dados (acima) e reconexão.
Autenticação falhando
Reconecte com /connect, confirme a validade da chave e verifique se a rede alcança a API do provedor — em ambientes corporativos, cheque a política de rede e proxy.
Copiar/colar não funciona no Linux
Instale um utilitário de clipboard: wl-clipboard (Wayland) ou xclip/xsel (X11). Headless: xvfb + DISPLAY. A detecção prefere Wayland quando presente.
Desktop: "Connection Failed" ou splash infinito
Quase sempre um servidor default configurado que não existe mais. No picker de servidores, limpe o default; remova a seção server da config; desfaça MVCODE_PORT do ambiente. No Windows, confirme o runtime WebView2; em Wayland, tente OC_ALLOW_WAYLAND=1 ou uma sessão X11.
Desktop: UI branca ou congelada
Recarregue o webview pelo menu (macOS), saia e reabra por completo, e — em último caso — apague os arquivos de estado do app (*.settings.dat, *.global.dat) no diretório de dados do desktop.
Notificações não aparecem
O desktop só notifica com permissão do SO concedida e a janela fora de foco. Na TUI, attention.enabled precisa estar ligado no tui.json.
Lento no Windows
Filesystem e ferramentas rendem mais no WSL — especialmente em repositórios grandes.
04Pedindo ajuda com contexto
Ao acionar o suporte, anexe: versão (mvcode --version), sistema, o trecho relevante do log em DEBUG e — quando fizer sentido — a config resolvida com segredos removidos. Um report com esses quatro itens resolve em uma ida.