Solução de problemas
Problemas comuns e como investigar cada cenário no console da Zenifra.
Falha no deploy
"Build failed"
Verifique os logs de build na aba Logs de Build da página do projeto no console. Se preferir terminal, use zenifra deploy watch ou zenifra builds logs.
| Erro | Correção |
|---|---|
npm ERR! Cannot read properties of undefined | Revise package.json e package-lock.json |
Cannot find module | Confirme se as dependências estão declaradas corretamente |
pip install falhou | Verifique o requirements.txt |
| Falha no build customizado | Revise os comandos pre-build, build e start configurados no projeto |
| Build sem etapas úteis | Confirme se start está configurado e se build só foi preenchido quando o projeto realmente precisa dele |
"App crashed on startup"
Verifique os logs do serviço no console.
| Erro | Correção |
|---|---|
EADDRINUSE | Verifique se a aplicação está escutando na porta esperada |
ECONNREFUSED | Revise a URI do banco ou confirme se o banco está acessível |
Cannot find module | Dependência ausente no projeto |
| Porta incorreta | Confirme se o campo Porta configurado no projeto corresponde à porta usada pela aplicação |
Importante: A Zenifra não define a porta automaticamente. O valor configurado no campo Porta deve ser o mesmo valor em que sua aplicação realmente escuta.
Problemas de conexão com o banco
"Connection refused"
Verifique os dados de conexão no console.
Confirme:
- o banco foi criado no console
- a
DATABASE_URLfoi configurada manualmente no projeto HTTP - host, porta, usuário, senha e nome do banco foram copiados corretamente
"Too many connections"
Soluções comuns:
- use pool de conexões na aplicação
- revise vazamentos de conexão no código
- analise se a quantidade atual de instâncias do banco ou da aplicação está adequada
Problemas de performance
Alto uso de memória
Verifique:
- vazamentos de memória
- payloads grandes
- falta de paginação
- plano abaixo da necessidade atual
Respostas lentas
Verifique:
- queries de banco e necessidade de índices
- falta de cache
- respostas muito grandes
- número insuficiente de instâncias para a carga atual
Logs vazios
Verifique:
- se o projeto está em status Executando
- se a aplicação está escrevendo em
stdout - se o plano atual permite logs
Importante: logs da aplicação e logs de build são fluxos diferentes. A aba Logs de Build mostra a publicação GitHub; a área de logs do projeto mostra a aplicação depois que ela inicia.
Estados do projeto
| Status | Significado |
|---|---|
| Criando | Projeto ainda em processo de build e inserção na infraestrutura |
| Parado | Nenhuma instância rodando; projeto inacessível |
| Executando | Projeto rodando normalmente na infraestrutura |
Observações sobre Parado
- por hora + armazenamento efêmero: para de cobrar a execução
- por hora + armazenamento persistente: continua cobrando o storage
- mensal/anual: parar não altera o valor final do contrato
Domínio personalizado não funciona
Verifique:
- se o domínio foi adicionado no painel da Zenifra exatamente como será acessado, por exemplo
www.seudominio.com.br - se o subdomínio aponta para o destino gerado pela Zenifra, normalmente via
CNAME - se o domínio raiz (
seudominio.com.br) usa provedor com CNAME flattening, já que muitos provedores não aceitamCNAMEcomum no root (@) - se todos os registros TXT de validação SSL em
_acme-challengeforam publicados - se o DNS já propagou nos servidores autoritativos do domínio
Para verificar um subdomínio www, use:
dig www.seudominio.com.br CNAME
dig _acme-challenge.www.seudominio.com.br TXT
curl -Iv https://www.seudominio.com.br/Se o painel da Zenifra mostrar dois registros TXT com o mesmo nome, mantenha os dois valores publicados ao mesmo tempo. Não substitua um token pelo outro enquanto o certificado SSL estiver pendente.
HTTPS falha, mas o CNAME está correto
Isso normalmente indica que a validação do certificado ainda não terminou. Confira:
- se todos os tokens TXT aparecem na resposta DNS
- se não existe apenas um dos tokens quando o painel mostra dois
- se o provedor DNS salvou o registro no host correto, como
_acme-challenge.www - se a autoridade certificadora já teve tempo de processar a validação
Enquanto o SSL está pendente, o domínio pode resolver para a Zenifra, mas o handshake HTTPS ainda pode falhar. Aguarde a emissão do certificado depois que os registros TXT estiverem corretos.
Domínio raiz não aceita CNAME
Provedores como Registro.br podem não permitir CNAME no domínio raiz (@). Nesse caso:
- mova os nameservers para um provedor com CNAME flattening, como Cloudflare
- ou redirecione o domínio raiz para
wwwusando um serviço externo com HTTPS
Não aponte o domínio raiz para IPs copiados de respostas DNS da Cloudflare ou de exemplos antigos. Esses IPs podem mudar e não são o destino estável do projeto.