O que acontece quando o VS Code perde a conexão com o GDB
O erro aparece na barra inferior do VS Code quando o CMake Tools tenta iniciar uma sessão de depuração e o GDB fecha ou devolve algo inesperado. A mensagem completa geralmente começa com unable to start debugging. unexpected gdb output from command e segue com uma linha bruta que o parser não consegue ler. Na minha experiência, isso raramente é um bug no GDB em si. Normalmente é configuração, permissão ou alguma extensão interferindo no processo de inicialização.
unable to start debugging. unexpected gdb output from command
Para resolver, você precisa reconstruir o contexto da falha. O VS Code chama um comando que lança o GDB em modo servidor ou como processo conectado, e se a primeira linha de saída não corresponder ao esperado, ele aborta. Isso costuma acontecer quando o binário do GDB foi trocado, quando um shell script intercepta o caminho, ou quando variáveis de ambiente mudam entre o terminal e o ambiente do VS Code. A maior parte das vezes a correção leva menos de dez minutos se você já sabe onde olhar. Meu caso mais recente envolveu um projeto em Linux no WSL2. O GDB padrão era o do Ubuntu, mas eu tinha instalado uma versão mais nova via apt em /usr/local/bin/gdb-14. Esse diretório estava no PATH antes do /usr/bin, então o VS Code puxava a versão nova sem avisar. A versão nova trazia uma mudança na formatação da linha inicial de saída que o CMake Tools não esperava. A solução foi remover o link simbólico em /usr/local/bin/gdb-14, deixar o VS Code usar o /usr/bin/gdb padrão, e reiniciar a sessão de depuração. Só isso. Sem reiniciar o WSL, sem reinstalar extensões.
Como diagnosticar passo a passo
O primeiro ponto é confirmar qual executável está sendo invocado. Abra o terminal integrado do VS Code e rode o comando que aparece nos logs da Depuração. Se você não vê o comando, abra Output e mude o canal para CMake/Make Debug ou Debug Console, dependendo da extensão que está usando. Anote o caminho completo do GDB. Depois, rode esse mesmo caminho manualmente no terminal e veja a primeira linha de saída. Se a primeira linha não for algo como GNU gdb, o problema é claro. O GDB correto falha em iniciar, um wrapper substituiu o binário, ou as variáveis de ambiente estão corrompidas. Se a primeira linha estiver normal, o erro provavelmente está em outro lugar. Pode ser um arquivo launch.json mal configurado, um caminho errado para o binário compilado, ou conflito com outra ferramenta como LLDB quando o projeto foi migrado de plataforma.
Vale checar também o conteúdo de launch.json e tasks.json. Linhas com preLaunchTask que modificam PATH ou LD_LIBRARY_PATH causam esse tipo de erro silencioso. O VS Code executa a task, o PATH muda, e o GDB que o launch.json espera não existe mais no novo contexto. Remova tarefas desnecessárias de pré-inicialização e teste direto. Isso elimina boa parte dos falsos positivos.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Cenários comuns e soluções práticas
Extensões de Python ativadas acidentalmente podem interferir em projetos C/C++ se o launch.json herdar configurações de outro workspace. Verifique se há múltiplos arquivos de configuração na pasta .vscode, especialmente settings.json em níveis diferentes. Settings aninhados sobrescrevem uns aos outros e geram caminhos inesperados para o depurador. Em Windows, o erro também aparece com frequência quando o GDB está instalado via MSYS2 ou Cygwin e o VS Code tenta rodá-lo pelo PowerShell ou CMD padrão. O GDB do MSYS2 espera um ambiente Cygwin e falha com saída não padronizada quando invocado fora dele. A correção é usar a versão mingw-w64 do GDB em vez da versão Cygwin, ou chamar o GDB diretamente via terminal MSYS2 e apontar o launch.json para esse executável específico.
Outro cenário recorrente envolve depuração remota com gdbserver. Se o gdbserver estiver em uma máquina diferente, o VS Code conecta via TCP e o GDB local recebe saída parcial. A mensagem de erro pode aparecer mesmo quando a conexão funciona, porque o parsing espera uma linha de status que só chega após segundos. Nesses casos, aumentar o timeout em launch.json resolve. Defina um valor maior para debugServerArguments ou adicione wait-for-gdb no gdbserver e espere ele responder antes de enviar comandos. Existem limitações que precisam ser ditas claramente. Corrigir o GDB não resolve problemas de breakpoints que falham por falta de símbolos. Se o binário foi compilado com -Os ou -s, o GDB pode iniciar normalmente mas não parar onde você espera. Isso não tem relação com o erro de inicialização, mas muitos usuários confundem os dois. Compile com -g -O0 durante o desenvolvimento e apenas mude o nível de otimização para releases.
Quando nenhuma correção óbvia funciona
Às vezes o problema está em camadas mais profundas. Extensões como CodeLLDB, Cortex-Debug ou PlatformIO sobrescrevem o comportamento padrão de depuração C/C++. Se você tem múltiplas extensões de depuração instaladas, o VS Code pode escolher a errada automaticamente. Desabilite todas exceto C/C++ Extension Pack do Microsoft, limpe a cache do CMake Tools com o comando CMake: Clean Reconfigure, e tente novamente. Se o erro persistir após todas as verificações acima, a alternativa mais rápida é desistir do CMake Tools como intermediário e rodar o GDB manualmente. Abra um terminal, navegue até a pasta do build, invoque o GDB com o binário correto, dê run, e use attach se necessário. Você perde a integração visual do debugger, mas confirma se o problema é no GDB ou na camada do VS Code. Em quase todos os casos que já vi, a depuração manual funciona perfeitamente enquanto a automática falha por causa de configuração específica do workspace.
Uma última observação útil. Salve logs detalhados antes de limpar qualquer coisa. O comando CMake: Set Logging Level para Debug gera arquivos temporários que mostram exatamente qual comando foi executado, qual PATH estava ativo, e qual saída o GDB retornou. Sem esses logs, você gasta horas testando hipóteses no escuro. Com os logs, o diagnóstico costuma levar dois ou três minutos.
