Referência v3
Voltar à plataforma

Troubleshooting

Erros reais, causas reais, soluções reais.

Erros de inicialização

ErroCausaSolução
JWT_SECRET deve ter pelo menos 32 caracteres JWT_SECRET ou JWT_API_SECRET muito curto no .env Gere com openssl rand -hex 32 e cole no .env
Configuração do banco incompleta DB_HOST, DB_NOME ou DB_USUARIO vazios Preencha todas as variáveis DB_* no .env
Página em branco / sem resposta APP_DEBUG=false esconde o erro Mude para APP_DEBUG=true temporariamente e veja o log PHP

Erros de módulo

ErroCausaSolução
NotFoundException: Não há binding ou classe para MinhaClasse Namespace errado ou composer dump-autoload não foi rodado Verifique o namespace (Src\Modules\NomeModulo\Camada) e rode composer dump-autoload
Rota retorna 404 mesmo existindo Módulo desativado ou arquivo de rotas não encontrado Verifique storage/modules_state.json e se o arquivo é Routes/web.php
Migration não executa Arquivo em subpasta (Migrations/1.0.0/) ou nome sem prefixo numérico Coloque o arquivo diretamente em Database/Migrations/ com nome 001_nome.php
PDO null no controller após instalar módulo Provider não carregado — extra.vupi.us ausente no composer.json do módulo Adicione "extra": {"vupi.us": {"providers": ["SuaClasse"]}} e rode composer dump-autoload
Classe não encontrada após instalar módulo pelo marketplace PHP-FPM usando OPcache antigo Confirme o serviço instalado. Neste ambiente: sudo systemctl reload php8.3-fpm

Erros de autenticação

ErroCausaSolução
401 Não autenticado Token ausente, expirado ou assinado com secret errado Verifique o header Authorization: Bearer TOKEN e se o token não expirou
403 Acesso restrito Rota admin acessada com token de usuário comum Use token gerado com JWT_API_SECRET (admin_system). Gere via php vupi setup opção 11
Token inválido: Emissor do token inválido JWT_ISSUER no .env diferente do que está no token Certifique-se que JWT_ISSUER é igual em todos os ambientes
429 Muitas requisições Rate limit atingido Aguarde o tempo indicado em Retry-After. Em dev, limpe storage/ratelimit/

Erros de banco de dados

ErroCausaSolução
SQLSTATE[42P01]: relation "tabela" does not exist Migration não foi executada php vupi migrate
O módulo está configurado para usar DB2 mas DB2 não está configurado connection.php retorna 'modules' mas DB2_* não está no .env Configure DB2_* no .env ou mude connection.php para 'core'
Banco não conecta em produção DB_HOST=localhost mas banco está em container Docker Use o nome do serviço Docker (postgres) ou o IP do host

Erros de dependências de módulo

ErroCausaSolução
Conflito de dependências detectado 🚫 Versão instalada não satisfaz a constraint do módulo Use constraint flexível: "guzzle": "^7.0 || ^6.5"
Deploy bloqueado por conflito mas constraint parece correta Versão no composer.lock tem prefixo v (ex: v7.8.1) O sistema normaliza automaticamente. Se persistir, rode composer update
Lib instalada mas não disponível no código Namespace PSR-4 não registrado no composer.json do módulo Adicione "autoload": {"psr-4": {"Src\\Modules\\NomeModulo\\": ""}}

Erros de e-mail

ErroCausaSolução
500 em /api/email/history Tabela email_history não existe php vupi migrate
503 SMTP não configurado MAILER_HOST vazio no .env Configure as variáveis MAILER_* no .env
E-mail enviado mas não chega Spam, SPF/DKIM não configurado ou senha de app incorreta Use senha de app (não a senha da conta). Configure SPF/DKIM no DNS do domínio

Dicas gerais de debug

bash
# Ver logs de erro do PHP-FPM em produção
tail -f /var/log/php-fpm/vupi.us-error.log

# Ver logs em tempo real (docker)
docker compose logs -f

# Limpar cache de rate limit (dev)
rm -f storage/ratelimit/*.json

# Limpar cache de módulos
rm -f storage/modules_cache.json

# Verificar status das migrations
php vupi migrate --status

# Testar conexão com banco
curl http://localhost:3005/api/db-status