Troubleshooting
Common problems and how to investigate each scenario in the Zenifra console.
Deploy failure
"Build failed"
Check the build logs in the console.
| Error | Fix |
|---|---|
npm ERR! Cannot read properties of undefined | Review package.json and package-lock.json |
Cannot find module | Confirm whether dependencies are declared correctly |
pip install failed | Check requirements.txt |
| Custom build failure | Review the pre-build, build, and start commands configured in the project |
"App crashed on startup"
Check the service logs in the console.
| Error | Fix |
|---|---|
EADDRINUSE | Check whether the application is listening on the expected port |
ECONNREFUSED | Review the database URI or confirm whether the database is accessible |
Cannot find module | Missing dependency in the project |
| Incorrect port | Confirm whether the Port field configured in the project matches the port used by the application |
Important: Zenifra does not define the port automatically. The value configured in the Port field must be the same value your application actually listens on.
Database connection problems
"Connection refused"
Check the connection details in the console.
Confirm:
- the database was created in the console
DATABASE_URLwas configured manually in the HTTP project- host, port, username, password, and database name were copied correctly
"Too many connections"
Common solutions:
- use connection pooling in the application
- review connection leaks in the code
- analyze whether the current number of database or application instances is adequate
Performance problems
High memory usage
Check:
- memory leaks
- large payloads
- lack of pagination
- a plan below current needs
Slow responses
Check:
- database queries and need for indexes
- lack of cache
- overly large responses
- insufficient number of instances for the current load
Empty logs
Check:
- whether the project is in Running status
- whether the application is writing to
stdout - whether the current plan allows logs
Project states
| Status | Meaning |
|---|---|
| Creating | Project is still in the build process and being inserted into the infrastructure |
| Stopped | No instance is running; project is inaccessible |
| Running | Project is running normally on the infrastructure |
Notes about Stopped
- hourly + ephemeral storage: execution billing stops
- hourly + persistent storage: storage billing continues
- monthly/yearly: stopping does not change the final contract value
Custom domain does not work
Check:
- whether the domain was added in the Zenifra panel exactly as it will be accessed, for example
www.yourdomain.com.br - whether the subdomain points to the target generated by Zenifra, usually through a
CNAME - whether the apex domain (
yourdomain.com.br) uses a provider with CNAME flattening, since many providers do not accept a regularCNAMEat the root (@) - whether all SSL validation TXT records under
_acme-challengewere published - whether DNS has propagated on the domain's authoritative nameservers
To verify a www subdomain, use:
dig www.yourdomain.com.br CNAME
dig _acme-challenge.www.yourdomain.com.br TXT
curl -Iv https://www.yourdomain.com.br/If the Zenifra panel shows two TXT records with the same name, keep both values published at the same time. Do not replace one token with the other while the SSL certificate is pending.
HTTPS fails, but the CNAME is correct
This usually means certificate validation has not finished yet. Check:
- whether all TXT tokens appear in the DNS response
- whether only one token exists when the panel shows two
- whether the DNS provider saved the record under the correct host, such as
_acme-challenge.www - whether the certificate authority has had enough time to process validation
While SSL is pending, the domain may resolve to Zenifra, but the HTTPS handshake can still fail. Wait for certificate issuance after the TXT records are correct.
Apex domain does not accept CNAME
Providers such as Registro.br may not allow CNAME on the apex domain (@). In that case:
- move the nameservers to a provider with CNAME flattening, such as Cloudflare
- or redirect the apex domain to
wwwusing an external service with HTTPS
Do not point the apex domain to IPs copied from Cloudflare DNS answers or old examples. Those IPs can change and are not the stable target for the project.