Tela de computador exibindo código HTML com erro de autenticação - debugging de código

Quando o Erro Mente: Como Debugar Problemas Onde a Mensagem Te Leva Pelo Caminho Errado

PorOlivetto

Eu já perdi 6 horas debugando um “erro de CORS” que, spoiler, não era CORS. A mensagem dizia uma coisa, o problema era outra completamente diferente. E não foi a primeira vez — nem a última — que uma mensagem de erro me levou pelo caminho mais longo possível.

Se você já ficou furioso com um NullPointerException que na verdade era um problema de configuração, ou com um 500 Internal Server Error que escondia um erro de digitação no SQL, esse post é pra você. Vou te mostrar como ler erros de verdade, como identificar quando a mensagem está mentindo, e como montar um sistema de debugging que te poupa horas de sofrimento.

O Log de Erros do AutoMente existe pra isso: transformar perrengue técnico em conhecimento. Cada erro que eu documento aqui é um erro que eu (e talvez você) nunca mais vai cometer.

Por Que as Mensagens de Erro Mentem (E Mentem Bastante)

Erros em software são como sintomas no corpo humano. Dor de cabeça pode ser desidratação, estresse, ou um tumor. O sintoma é real, mas a causa raiz pode estar em qualquer lugar. Em código, isso é pior, porque a mensagem de erro é gerada pelo código que falhou, não pelo código que causou a falha.

Existem três tipos principais de “erros mentirosos”:

1. O Erro Cascata

Algo quebra no fundo da stack. A camada acima tenta lidar com isso, não consegue, e gera uma mensagem genérica. A camada acima faz a mesma coisa. Quando chega em você, a mensagem diz CONNECTION REFUSED quando na verdade era um certificado SSL expirado três camadas abaixo.

# O que você vê:
Connection refused: localhost:5432

# O que realmente aconteceu:
# 1. SSL cert expirou às 00:00
# 2. PG bouncer reject a conexão com TLS
# 3. App recebe "connection refused"
# 4. Log mostra só a mensagem genérica

2. O Erro Assíncrono

O erro aparece 30 segundos depois do problema real, em um callback ou Promise rejection que não tem contexto nenhum sobre o que aconteceu. Você olha pro stack trace e ele aponta pra um lugar que não tem nada a ver com nada.

3. O Erro Traduzido Demais

Alguém na equipe (ou um framework) decidiu “simplificar” as mensagens de erro. Pegou um erro técnico específico e transformou em "Algo deu errado. Tente novamente." Obrigado. Muito útil.

Código PHP e HTML exibindo erro de login em formulário - exemplo de debugging em produção

Anatomia de um Stack Trace: Leia Como Um Detetive

Stack traces não são spam visual. São a linha do tempo de um crime. O segredo é saber ler de baixo pra cima — a primeira linha (o topo) é onde o erro foi lançado, mas as linhas do fundo são onde tudo começou.

Vamos dissecar um stack trace real de uma aplicação Node.js:

Error: Cannot read properties of undefined (reading 'email')
    at UserController.getProfile (src/controllers/user.js:47:32)
    at Layer.handle [as handle_request] (node_modules/express/lib/router/layer.js:95:5)
    at next (node_modules/express/lib/router/route.js:149:13)
    at authMiddleware (src/middleware/auth.js:23:8)
    at Layer.handle [as handle_request] (node_modules/express/lib/router/layer.js:95:5)

O que a maioria das pessoas faz: olha pra linha 1, vê reading 'email', e vai direto no user.js:47 verificar se user.email existe. Perda de tempo.

O que um debugador experiente faz:

  • Lê o stack completo — nota que passou por authMiddleware
  • Pergunta: “Será que o middleware de autenticação está retornando um usuário incompleto?”
  • Verifica: olha auth.js:23 e descobre que o middleware retorna req.user = decoded.id ao invés de req.user = decoded
  • Resultado: corrige em 2 minutos ao invés de 2 horas

O Método REVA: Debugging Sistemático Que Funciona

Depois de anos cometendo os mesmos erros de debugging, criei um método simples que me salvou incontáveis horas. Chamo de REVA:

R — Reproduza Com Precisão

Não adianta “às vezes acontece”. Se você não consegue reproduzir consistentemente, você não vai conseguir debugar. Anote:

  • URL exata, método HTTP, payload
  • Ambiente (dev, staging, prod)
  • Horário e timezone
  • Estado do sistema (cache quente ou frio? primeira requisição?)
# Script mínimo de reprodução
curl -X POST https://api.exemplo.com/users \
  -H "Authorization: Bearer TOKEN_EXPIRADO" \
  -H "Content-Type: application/json" \
  -d '{"name": "teste", "role": "admin"}'
  
# Resultado: 500 Internal Server Error
# Reproduzível? SIM — toda vez que token expirado + role admin

E — Expanda O Contexto

O erro é a ponta do iceberg. Você precisa ver o que está embaixo da água:

  • Aumente o nível de log pra DEBUG ou TRACE
  • Ative query logging no banco de dados
  • Verifique variáveis de ambiente relevantes
  • Compare com uma requisição que funciona

Eu mantenho um alias no meu .bashrc pra isso:

# Debug rápido de variáveis de ambiente
alias envcheck='env | grep -E "(DATABASE|REDIS|API_KEY|SECRET)" | sed "s/=.*/=***/" '

# Debug de conexão com banco
alias dbping='python3 -c "
import psycopg2, os
try:
    conn = psycopg2.connect(os.environ.get(\"DATABASE_URL\"))
    print(\"✅ DB conectado:\", conn.get_backend_pid())
    conn.close()
except Exception as e:
    print(\"❌ DB erro:\", e)
"'

V — Verifique Hipóteses (Não “Tente Coisas”)

Tem uma diferença fundamental entre “vou tentar mudar isso aqui” e “minha hipótese é X, vou verificar se X é verdade”. Um é debugging, o outro é adivinhação.

Exemplo prático:

Erro: ENOENT: no such file or directory, open '/app/config/production.json'

❌ Tentativa cega: “Vou criar o arquivo production.json”

✅ Hipótese: “O arquivo existe no container mas o working directory mudou”

# Verificação da hipótese
docker exec myapp pwd
# /  ← AH! Working directory é / ao invés de /app

docker exec myapp ls /app/config/
# production.json  ← O arquivo existe!

# Solução real: corrigir WORKDIR no Dockerfile

A — Anote Tudo

Se você não documenta, vai repetir. Tenho um arquivo debug-log.md no meu projeto onde anoto:

## 2026-05-06 — Erro 500 no endpoint /api/orders

**Sintoma:** 500 Internal Server Error ao criar pedido com cupom expirado
**Causa real:** Cupom validator não tratava null no campo discount_percentage
**Tempo perdido:** 45 min (15 min com REVA)
**Lição:** Sempre validar null em campos opcionais antes de operações matemáticas
**Fix:** PR #347 - adicionado null check no CupomValidator.java:23

5 Ferramentas Que Mudaram Meu Debugging

1. ripgrep (rg) Para Busca No Código

Esquece grep -r. Ripgrep é 100x mais rápido e ignora arquivos irrelevantes automaticamente.

# Encontrar onde o erro é gerado
rg "CONNECTION_REFUSED" --type py -C 3

# Encontrar todos os lugares que chamam a função problemática
rg "def send_email" --type py -l | head -20

2. jq Para Ler Logs JSON

Se seus logs são JSON (e deveriam ser), jq é indispensável:

# Filtrar erros dos últimos 5 minutos
cat app.log | jq 'select(.level == "error" and .timestamp > "2026-05-06T20:55") | {message, stack: .stack_trace[0:3]}'

3. strace / dtruss Para Ver O Que O Processo Realmente Faz

Quando nada mais funciona, ver as syscalls do processo revela tudo:

# Descobrir qual arquivo o processo tenta abrir
strace -e trace=openat -p $(pgrep -f "myapp") 2>&1 | grep config
# openat(AT_FDCWD, "/etc/myapp/config.yaml", O_RDONLY) = -1 ENOENT

4. Charles Proxy / mitmproxy Para Debugar APIs

Quando o erro está “entre” o frontend e o backend, você precisa ver o que realmente viaja no fio:

# mitmproxy — intercepta e mostra todas as requests
mitmproxy --mode regular --listen-port 8080

# Ou via curl com verbose
curl -v https://api.exemplo.com/endpoint 2>&1 | less

5. bat Para Ler Código Com Syntax Highlighting

Substitui cat com highlighting e números de linha, essencial pra debugar direto no terminal:

# Ver o arquivo com contexto do erro
bat src/controllers/user.js --highlight-line 47

Tela de computador exibindo mensagem de falha na autenticação - debugging de sistemas

Perrengue Real: O Deploy Que Quebrou Tudo às 23h47

🎯 Desafio Técnico: Sexta-feira, 23h47. Deploy de emergência pra corrigir um bug de segurança. O deploy termina, e todo endpoint começa a retornar 502 Bad Gateway. A mensagem de erro do nginx diz "upstream prematurely closed connection". Você tem 15 minutos antes que o cliente perceba.

Pista: O deploy mudou uma variável de ambiente de DATABASE_URL=postgres://user:pass@host:5432/db para DATABASE_URL=postgresql://user:pass@host:5432/db (postgres → postgresql).

Esse perrengue aconteceu comigo. O erro do nginx era 100% genuíno — o upstream realmente fechava a conexão. Mas a causa era que o ORM (SQLAlchemy, no caso) não reconhecia o scheme postgresql:// naquela versão específica e crashava silenciosamente durante a inicialização.

A solução? Não era mexer no nginx. Era trocar a URL de volta pra postgres://. Mas eu perdi 10 preciosos minutos achando que era problema de proxy antes de aplicar o REVA e verificar o log da aplicação.

Lição que anotei e nunca mais esqueci: 502 não é problema de nginx. 502 é “o processo atrás do nginx morreu ou nunca subiu”. Verifique o processo primeiro.

Como Criar Mensagens de Erro Que Não Mentem

Já que sofremos com erros ruins, quebramos o ciclo. Quando você for escrever código que gera erros, siga essas regras:

Regra 1: Inclua O Contexto

# ❌ Ruim
raise ValueError("Invalid input")

# ✅ Bom  
raise ValueError(
    f"Invalid role '{role}' for user {user_id}. "
    f"Expected one of: {VALID_ROLES}. "
    f"Request source: {request.source_ip}"
)

Regra 2: Sugira A Solução

# ❌ Ruim
console.error("Database connection failed")

# ✅ Bom
console.error(
  `Database connection failed to ${DB_HOST}:${DB_PORT}. ` +
  `Checked: 1) Is DB running? (ping: ${dbReachable}) ` +
  `2) Are credentials valid? (auth test: ${authOk}) ` +
  `3) Is SSL required? (SSL mode: ${sslMode})`
)

Regra 3: Use Error Codes Únicos

Cada tipo de erro recebe um código único que pode ser pesquisado na documentação:

# Em vez de mensagens genéricas
throw new AppError("AUTH_TOKEN_EXPIRED", {
  statusCode: 401,
  userMessage: "Sua sessão expirou. Faça login novamente.",
  devMessage: "JWT expirou em " + decoded.exp + ". Current time: " + Date.now(),
  docUrl: "https://docs.exemplo.com/errors/AUTH_TOKEN_EXPIRED"
});

Debugging em Produção: O Guia De Sobrevivência

Debugar em produção é uma arte diferente. Você não pode simplesmente adicionar console.log e reiniciar. Precisa ser cirúrgico.

Observabilidade > Debugging

Se você precisa “debugar” em produção com frequência, seu sistema de observabilidade está falhando. Antes do erro acontecer, você deveria ter:

  • Structured logging — logs em JSON com correlation IDs
  • Distributed tracing — Jaeger, Zipkin, ou AWS X-Ray
  • Métricas de negócio — não apenas CPU/RAM, mas “pedidos por minuto”, “latência de pagamento”
  • Alertas inteligentes — não “CPU > 80%”, mas “taxa de erro > 1% nos últimos 5 minutos”
# Exemplo de log estruturado que salva vidas
{
  "timestamp": "2026-05-06T21:00:00Z",
  "level": "error",
  "correlation_id": "req-abc123",
  "service": "order-service",
  "operation": "create_order",
  "error_code": "COUPON_INVALID",
  "context": {
    "coupon_code": "PROMO20",
    "cart_total": 150.00,
    "user_id": "usr-456"
  },
  "stack_trace": "..."
}

O Comando Que Salva Noites De Sexta

# Ver os últimos 100 erros de um container, com timestamp
docker logs --since 5m --tail 100 myapp 2>&1 | grep -i error

# Ou, se usa kubectl
kubectl logs --since=5m deployment/myapp | jq 'select(.level=="error")'

Mantenha esses comandos num sistema de produtividade acessível. Quando o pânico bate, você não quer ter que lembrar a sintaxe do kubectl logs.

Checklist: Antes De Pedir Ajuda

Antes de abrir uma issue, mandar mensagem pro colega, ou postar no Stack Overflow, passe por esse checklist:

  • ✅ Li o stack trace completo (de baixo pra cima)
  • ✅ Pesquisei a mensagem de erro exata no Google
  • ✅ Verifiquei se o erro é reproduzível consistentemente
  • ✅ Testei com uma versão simplificada (isolando variáveis)
  • ✅ Verifiquei logs de serviços relacionados (banco, cache, fila)
  • ✅ Comparei com um cenário que funciona (diff mental)
  • ✅ Verifiquei mudanças recentes (git log --since="2 hours ago")
  • ✅ Confirmei que variáveis de ambiente estão corretas

Se passou por tudo isso e ainda não achou, parabéns — você encontrou um bug interessante. Agora sim, peça ajuda com contexto completo.

Conclusão: O Erro É Seu Professor Mais Sincero

Erros não são inimigos. São informações. Cada erro que você debuga te ensina algo sobre o sistema que nenhuma documentação vai te dar. O segredo é parar de tratar erro como incômodo e começar a tratar como diagnóstico.

O método REVA — Reproduza, Expanda, Verifique, Anote — não é perfeito, mas transforma debugging de adivinhação em método científico. E método científico, diferente de chute, é reproduzível.

Se você aplicar uma coisa desse post, aplique essa: antes de abrir o código, leia o stack trace completo. De verdade. Linha por linha. Isso sozinho vai te economizar 40% do tempo de debugging.

E aí, qual foi o erro mais mentiroso que você já encontrou? Qual erro te fez perder mais tempo e depois era algo trivial? Compartilha nos comentários — o próximo dev que passar pelo mesmo perrengue vai te agradecer.

Para mais histórias de perrengue técnico e soluções reais, acompanhe o Log de Erros aqui no AutoMente. E se você quer transformar seus próprios desastres em aprendizado, comece a documentar. Um debug-log.md no repositório já é um começo.

Posts Similares