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 no console.
| 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 |
"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
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.