Solução de problemas

Diagnóstico rápido: a aplicação não responde

Siga a ordem abaixo. Cada passo elimina uma causa comum e leva menos de um minuto.

Se nada disso resolver, fale com o suporte seguindo a central de ajuda.

Falhas de build em projetos Git

A Zenifra preserva a causa principal da falha mesmo quando o diagnóstico adicional não está disponível, em projetos GitHub e Forgejo. Consulte primeiro os Logs de build e a orientação exibida no projeto.

Quando o acesso salvo ao repositório deixa de existir, a Zenifra tenta localizar e validar novamente o mesmo repositório, sem trocar a organização, o nome ou a branch. Se essa recuperação não for possível, use Reconectar repositório no projeto e depois inicie uma nova build. Essa ação não inicia uma build automaticamente.

Problemas comuns e como investigar cada cenário no console da Zenifra.

Falha no deploy

"Build failed"

Verifique os logs de build em Logs de build na página do projeto no console. Se preferir terminal, use zenifra deploy watch ou zenifra builds logs.

"App crashed on startup"

Verifique os logs da aplicação no console (disponíveis em todos os planos).

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:

1. o banco foi criado no console
2. a DATABASE_URL foi configurada manualmente no projeto HTTP
3. host, porta, usuário, senha e nome do banco foram copiados corretamente
4. a conexão usa TLS como na URI do console (sslmode=verify-full no PostgreSQL); no node-postgres, remova sslmode e sslrootcert da URI e use ssl: true, como no início rápido com banco

"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á como Projeto rodando
• se a aplicação está escrevendo em stdout ou stderr
• se a mensagem esperada ainda está no trecho recente: os logs são lidos ao vivo das instâncias, sem histórico retido

Importante: logs da aplicação e logs de build são fluxos diferentes. Logs de build mostra a publicação de projetos Git; a área de logs do projeto mostra a aplicação depois que ela inicia.

Estados do projeto

Observações sobre Projeto 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

Limite do plano Free atingido

Ao criar um projeto, o console mostra o aviso Limite do plano Free atingido quando a organização já usou os recursos gratuitos. A mensagem indica qual limite foi alcançado:

Os limites de cada plano gratuito estão em Limites e quotas.

Domínio personalizado não funciona

Verifique:

1. se o domínio foi adicionado no painel da Zenifra exatamente como será acessado, por exemplo www.seudominio.com.br
2. se o subdomínio aponta para o destino gerado pela Zenifra, normalmente via CNAME
3. se o domínio raiz (seudominio.com.br) usa provedor com CNAME flattening, já que muitos provedores não aceitam CNAME comum no root (@)
4. se todos os registros TXT de validação SSL em _acme-challenge foram publicados
5. 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 www usando um serviço externo com HTTPS

Não aponte o domínio raiz para IPs copiados de respostas DNS ou de exemplos antigos. Esses IPs podem mudar e não são o destino estável do projeto.

Precisa de mais ajuda?

• Central de ajuda e suporte: o que enviar para receber uma resposta rápida
• Status da plataforma
• Suporte por e-mail ou WhatsApp +55 (11) 5199-3013