Troubleshooting¶
Este documento lista problemas comuns e suas soluções.
Índice¶
Backend¶
Erro: "failed to connect to database"¶
Causas: - PostgreSQL não está rodando - Credenciais incorretas - Banco não existe - Porta incorreta
Soluções:
# 1. Verificar PostgreSQL está rodando
sudo systemctl status postgresql # Linux
brew services list | grep postgresql # macOS
# 2. Verificar banco existe
psql -U postgres -l | grep billings_ease
# 3. Testar conexão manual
psql -U billings_user -d billings_ease_dev -h localhost
# 4. Verificar variáveis de ambiente
echo $DB_HOST
echo $DB_USER
Erro: "migration failed"¶
Causas: - Migração já executada - Dados incompatíveis - Permissões insuficientes
Soluções:
# 1. Verificar estado do banco
psql -U billings_user -d billings_ease_dev -c "\d"
# 2. Executar migração específica para ver erro detalhado
psql -U billings_user -d billings_ease_dev -f migrations/XXX_migration.sql
# 3. Verificar logs do backend
# Migrações são executadas na inicialização
Erro: "port already in use"¶
Causas: - Outro processo usando a porta - Instância anterior não finalizada
Soluções:
# 1. Encontrar processo
lsof -i :8080 # Linux/macOS
netstat -ano | findstr :8080 # Windows
# 2. Matar processo
kill -9 <PID>
# 3. Ou mudar porta no .env
PORT=8081
Frontend¶
Erro: "Cannot connect to API"¶
Causas:
- Backend não está rodando
- VITE_API_URL incorreto
- CORS não configurado
Soluções:
# 1. Verificar backend está rodando
curl http://localhost:8080/health
# 2. Verificar variável de ambiente
echo $VITE_API_URL
# Deve ser: http://localhost:8080/api
# 3. Verificar CORS no backend permite origem do frontend
Erro: "Module not found"¶
Causas: - Dependência não instalada - Import path incorreto - Cache do Vite
Soluções:
# 1. Reinstalar dependências
rm -rf node_modules package-lock.json
npm install
# 2. Limpar cache do Vite
rm -rf node_modules/.vite
# 3. Verificar import paths
# Usar @/ para imports absolutos
Banco de Dados¶
Erro: "relation does not exist"¶
Causas: - Tabela não criada - Migrações não executadas - Schema incorreto
Soluções:
# 1. Verificar tabelas existentes
psql -U billings_user -d billings_ease_dev -c "\dt"
# 2. Executar AutoMigrate
# Backend executa automaticamente na inicialização
# 3. Executar migrações manuais
go run ./cmd/migrate
Erro: "duplicate key value"¶
Causas: - Violação de constraint único - Dados duplicados
Soluções:
-- Verificar constraint
SELECT conname, contype FROM pg_constraint WHERE conrelid = 'users'::regclass;
-- Verificar dados duplicados
SELECT email, COUNT(*) FROM users GROUP BY email HAVING COUNT(*) > 1;
Autenticação¶
Erro: "Invalid or expired token"¶
Causas: - Token expirado - Secret incorreto - Token inválido
Soluções:
# 1. Verificar JWT_SECRET no backend
echo $JWT_SECRET
# 2. Fazer novo login
# 3. Verificar expiração do token (24 horas para access, 7 dias para refresh)
Erro: "EMAIL_NOT_VERIFIED"¶
Causas: - Email não foi verificado - Token de verificação expirado
Soluções:
# 1. Reenviar verificação
POST /api/auth/resend-verification
# 2. Verificar email foi enviado
# 3. Verificar token não expirou (24 horas)
Integrações¶
Erro: "R2 Storage not configured"¶
Causas: - Variáveis R2 não configuradas - Credenciais inválidas
Soluções:
# 1. Verificar variáveis
echo $R2_ACCESS_KEY_ID
echo $R2_SECRET_ACCESS_KEY
# 2. Testar conexão (opcional)
# Upload de arquivo pequeno para testar
# 3. Sistema funciona sem R2, mas uploads não funcionarão
Erro: "Email service not configured"¶
Causas: - SendGrid ou SMTP não configurado - Credenciais inválidas
Soluções:
# 1. Configurar SendGrid ou SMTP
# SendGrid:
SENDGRID_API_KEY=your-key
# Ou SMTP:
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=email@gmail.com
SMTP_PASSWORD=app-password