Unable To Start Debugging. Unexpected Gdb Output From Command

Arrumar o erro ao inicializar o depurador no VS Code

Se você já tentou rodar um programa em C ou C++ pelo VS Code e recebeu a mensagem unable to start debugging. unexpected gdb output from command, sabe o quanto isso é frustrante. O erro aparece sem aviso, o terminal fica aberto com uma fila de linhas que parecem nonsense, e o ponto de interrupção nunca é atingido. Na prática, isso significa que o GDB foi chamado, respondeu algo inesperado e o VS Code desistiu antes mesmo de conectar. O VS Code usa o GDB como motor de debug para Linux. Ele lança uma cadeia de comandos: primeiro gdb, depois set non-stop on, set pagination off, -gdb-set stop-on-solib-events 1, e por aí vai. Se o GDB responder com texto que não está no formato esperado — como uma mensagem de erro, um prompt de shell travado, ou código binário escorregando pelo pipe — o adaptador de debug quebra com esse erro. O problema raramente é o GDB em si. É quase sempre configuração, caminho errado, ou algo interferindo na saída padrão do processo. Minha primeira vez com esse erro foi num projeto embedded onde eu tinha configurado um Makefile que redirecionava stderr para um log de Build Output dentro da própria janela do terminal. O adaptador do VS Code achava que aquelas linhas eram saída do GDB. Demorei uma hora para perceber que o problema não era o GDB, mas sim a flag -v que eu tinha deixado no Makefile e que despejava warnings de compilação no stdout. Removi a flag, o debug funcionou na hora.

Como diagnosticar na prática

A primeira coisa que eu faço é verificar qual versão do GDB está sendo usada. Abro um terminal e rodo gdb --version. Se o resultado apontar para uma instalação diferente daquela que o VS Code encontra no PATH, o conflito já está identificado. Isso é mais comum do que se imagina, especialmente em máquinas com WSL, múltiplas instalações via apt e homebrew, ou ambientes Docker. Depois disso, olho o launch.json. O campo miDebuggerPath precisa apontar exatamente para o binário do GDB. Em sistemas Debian/Ubuntu, costuma ser /usr/bin/gdb. Em máquinas com cross-gcc, pode ser algo como /usr/bin/arm-linux-gnueabi-gdb. Um erro comum é colocar o caminho do compilador no lugar do depurador. O GCC não é o GDB, e o VS Code sabe disso — o adaptador reclama na hora. O campo program também precisa ser verificado. Ele deve apontar para o executável já compilado, não para o fonte. Já vi gente colocando o caminho do .c ou .cpp ali e se perguntando por que o GDB não iniciava. Obvio, mas acontece com frequência.

Configurações que resolvem a maior parte dos casos

O launch.json típico para C++ no Linux segue essa estrutura. Eu monto assim e raramente preciso mudar: { "version": "0.2.0",

"configurations": [ { "name": "(gdb) Launch",

"type": "cppdbg", "request": "launch", "program": "${workspaceFolder}/build/meu_programa",

"args": [], "stopAtEntry": false, "cwd": "${workspaceFolder}",

"environment": [], "externalConsole": false, "MIDebuggerPath": "/usr/bin/gdb",

"setupCommands": [ { "description": "Enable pretty-printing for gdb",

"text": "-enable-pretty-printing", "ignoreFailures": true }

], "preLaunchTask": "build" }

] } Se o seu projeto usa compilador cross, substitua o MIDebuggerPath pelo caminho correto do GDB cross. A flag "ignoreFailures": true no setupCommands é útil porque o GDB pode reclamar de recursos que não existem na versão instalada, mas isso não quebra o debug.

O preLaunchTask também merece atenção. Se ele existe, o VS Code roda antes de iniciar o GDB. O problema é que tarefas mal configuradas podem sujar o stdout e fazer o adaptador receber linhas que não reconhece. A solução é garantir que o task só produza saída em stderr ou nada. No tasks.json, usar "presentation": { "echo": false, "reveal": "silent", "focus": false } evita que mensagens do build contaminem a comunicação com o GDB.

Casos mais difíceis que já encontrei

Um deles aconteceu quando o sistema tinha dois GDBs instalados: um nativo em /usr/bin/gdb e outro em /usr/bin/gdb-multiarch. O VS Code resolvia o PATH de forma diferente dependendo se eu vinha do terminal integrado ou de um shell externo. A mensagem de erro mudava sutilmente entre rodada e rodada, o que tornava o diagnóstico ainda mais irritante. A solução foi ser explícito no miDebuggerPath e nunca confiar na resolução automática do PATH. Outro caso foi num container Docker onde o GDB estava instalado, mas o debugger não tinha permissão para attach a processos por causa de kernel.yama.ptrace_scope valendo 2. A mensagem de erro não era exatamente essa, mas o efeito era o mesmo: o GDB iniciava e fechava sem motivo aparente. O workaround foi rodar echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope antes de depurar, ou rodar o contêiner com --cap-add=SYS_PTRACE. Tem também o problema de espaços no caminho. Se o diretório do projeto tem um espaço, o GDB às vezes interpreta mal os argumentos e o adaptador recebe saída corrompida. Renomear a pasta do projeto resolve. Parece bobeira, mas é mais comum do que a documentação admite.

O que não adianta tentar

Reinstalar a extensão C/C++ do VS Code raramente resolve. O problema quase nunca está na extensão. Atualizar o GDB pode ajudar se a versão estiver muito desatualizada, mas em muitos casos a versão do repositório Ubuntu já é suficiente. O Versão does not need to be the latest for basic debugging. O que faz diferença é manter as ferramentas coerentes entre si: GCC, GDB e a extensão do VS Code precisam estar na mesma arquitetura e no mesmo ambiente. Misturar packages de diferentes repositórios costuma causar esses erros intermitentes. Também não adianta aumentar o debugTool ou brincar com flags de launch que não estão documentadas. O adaptador do VS Code já tem comportamento padrão bem testado. Forçar configurações alternativas geralmente piora a situação.

Resumo do que funciona

Verifique o miDebuggerPath. Confirme que aponta para o GDB correto. Verifique o program. Confirme que é o binário compilado. Certifique-se de que o preLaunchTask não gera stdout. Limpe o PATH para evitar ambiguidade entre GDBs. Evite espaços nos caminhos. Se estiver em WSL ou Docker, verifique permissões de ptrace. Se nada disso resolver, rode o GDB manualmente na linha de comando com os mesmos argumentos do launch.json para ver a saída real antes do adaptador interceptar. Na minha experiência, cerca de 80% dos casos se resolvem corrigindo o miDebuggerPath e limpando a saída do preLaunchTask. Os outros 20% são problemas de ambiente que exigem verificação manual do GDB. Se você quer um guia rápido de download e configuração, a extensão oficial do VS Code para C/C++ está disponível na marketplace do próprio editor. Não precisa de instalador separado. A instalação leva menos de dois minutos e já vem com o suporte ao GDB embutido.