Sílaba Tônica De Laranja

O que fazer quando seu código não compila e o erro vem em inglês

Eu estava configurando um pipeline de integração contínua há uns três anos quando o build quebrou com uma mensagem que eu não fazia ideia do que significava. O erro dizia algo como "permission denied, are you connected?" e o stack trace apontava para um volume docker que eu nem sabia que existia. Depois de duas horas quebrando a cabeça, descobri que era permissão de mount no path do certificado TLS. A solução foi ajustar as flags do daemon com um path absoluto e dar um chmod 644 no arquivo. Isso me ensinou uma coisa prática: erro em inglês muitas vezes é só informação mal traduzida pelo seu cérebro no cansaço. Muita gente trava quando o log vem todo em inglês técnico. Na verdade, a maior parte dos problemas segue um padrão repetitivo. Primeiro você lê a linha que começa com "Error" ou "Exception". Depois olha o número da linha no arquivo. O resto é caça ao caminho errado ou pacote faltando. Eu costumo salvar os erros mais comuns num arquivo de texto e deixar aberto em outra aba. Quando o problema aparece de novo, já sei onde procurar sem perder tempo. O primeiro passo é identificar qual tool está falhando. Se for npm, o erro costuma aparecer nos primeiros vinte linhas do log. Se for um container, o problema pode estar em qualquer camada entre o build e o run. Minha tática é usar grep ou Ctrl+F para buscar palavras-chave como "fatal", "failed", "cannot find" ou "undefined". Essas palavras quase sempre indicam o ponto exato da quebra. Às vezes o erro real está cinco linhas acima do que você vê primeiro, porque o stack trace empilha múltiplas camadas de exceção.

Um caso que tenho na memória é de um projeto React onde o ESLint falhava intermitentemente. O erro dizia que uma regra não existia, mas o pacote estava instalado. Descobri que o problema era cache do eslint com versões misturadas entre o node_modules do projeto e um global instalado via homebrew. A workaround que funcionou foi remover o cache com rm -rf ~/.eslintcache e rodar um npx eslint com o caminho explícito pro prefixo do projeto. Levei dois dias pra achar isso, e hoje gero esse comando em trinta segundos.

Tradução prática de termos técnicos

Vou listar os termos que mais aparecem e o que significam na prática: Exit code 1: falha genérica. Significa apenas que o processo terminou sem sucesso. Não dá pra saber o quê sem ler o log acima. Module not found: um import aponta pra um caminho que não existe ou o pacote não foi instalado. Verifique se o nome do arquivo está com a extensão certa. Em TypeScript às vezes falta o .ts ou .tsx no import.

Cannot find module: similar ao anterior, mas em runtime. O código compila mas não acha o arquivo na execução. Isso acontece muito com paths relativos que funcionam num OS e quebram em outro por causa de maiúsculas e minúsculas. ECONNREFUSED: alguma conexão de rede foi rejeitada. Pode ser um serviço que não subiu, uma porta errada, ou um firewall bloqueando. Cheque se o serviço alvo está rodando e em qual porta ele expõe. Segmentation fault: o processo tentou acessar memória que não pertence a ele. Comum em C++ ou Rust com unsafe, mas também pode aparecer em bridges nativas. A menos que você escreva código de baixo nível, isso raramente é seu problema direto. Atualize a versão do runtime ou do pacote nativo.

O problema dos pacotes com dependências conflitantes

Essa é a categoria que mais consome tempo. O erro aparece porque duas libs exigem versões diferentes da mesma dependência. O npm ou yarn resolve de forma diferente dependendo do lockfile. Minha abordagem é rodar o comando do gerenciador com --legacy-peer-deps quando o conflito é em peer dependencies e não em dependencies diretas. Isso contorna o problema sem precisar rebolar com versões intermediárias. Existe uma armadilha aqui: usar --legacy-peer-deps pode mascarar um problema real que vai explodir em produção. Por isso eu só aplico essa flag depois de confirmar que nenhuma dependência direta está incompatível. Faço uma verificação rápida com npm ls ou yarn why. Se a árvore de dependências mostrar ciclos estranhos ou versões duplicadas, o caminho certo é isolar o pacote problemático num workspace separado.

Como estruturar uma busca eficiente de solução

Eu copio a linha de erro inteira e colo no GitHub issues do repositório relevante. Se não achar nada útil lá, vou pro Stack Overflow com o tag do framework. Antes de postar, eu sempre verifico se o erro já foi reportado na última semana. Muitas vezes a correção já existe mas ainda não foi mergeada. Outro truque que funciona bem é olhar o changelog da versão em que o erro começou a aparecer. Se foi numa atualização recente, provavelmente é um breaking change documentado. Às vezes o readme não menciona, mas o CHANGELOG.md dentro do repo sim. Eu costumo manter um hábito de ler pelo menos os primeiros cinquenta pontos do changelog antes de subir de versão num projeto crítico.

Quando o erro é seu e quando é do ecossistema

Isso é importante distinguir. Erros do ecossistema geralmente aparecem pra muita gente ao mesmo tempo. Se você vê um pico de issues abertos num repo famoso num mesmo dia, provavelmente é um bug de release. Nestes casos, a melhor solução é esperar o patch ou fazer um downgrade controlado até a correção sair. Erros do seu lado normalmente envolvem configuração local, variáveis de ambiente esquecidas, ou caminhos absolutos que não fazem sentido no novo ambiente. Eu tenho um checklist mental que uso nessa situação: variáveis de ambiente estão setadas, o arquivo de configuração existe no caminho esperado, as permissões de arquivo estão corretas, e a versão do runtime bate com a exigida pelo projeto. Resolvendo esses quatro pontos, a maioria dos erros self-inflicted desaparece.

Um erro específico que mudou minha rotina

Depois daquele problema com ESLint e cache, eu parei de confiar em ferramentas globais. Passei a usar npx pra tudo que envolvia CLI, e configurei scripts no package.json que já vinham com os caminhos corretos embutidos. Isso eliminou cerca de setenta por cento dos erros que eu tinha antes. O custo foi configurar os scripts uma vez, mas o ganho foi contínuo. Projetos que eu puxava de colegas ou de repositórios novos agora rodavam sem ajuste manual na primeira execução. Eu também comecei a usar arquivos .env.example com todas as variáveis listadas, mesmo as que tinham valor default. Isso evita aquela situação em que alguém clona o repo, esquece de criar o .env, e leva três horas pra descobrir que faltava uma variável que deveria estar obvious. Parece besteira, mas é um dos problemas mais recorrentes que eu vejo em code review.

A regra que eu sigo hoje

Todo erro novo começa com leitura do log inteiro, não só da linha highlightada. Eu nunca pulo pra Google antes de entender o que o processo estava fazendo quando quebrou. Se o log não explica o suficiente, eu ativo modo debug e deixo rodar de novo. O tempo extra de debug quase sempre compensa, porque a segunda execução mostra o contexto que faltou na primeira. Só depois de ter informação suficiente eu busco ajuda externa. Esse ritmo me economiza horas por semana e reduz a ansiedade de depender de tradução automática pra entender o que aconteceu.