Troubleshooting

Quick diagnosis: the app is not responding

Follow the order below. Each step rules out a common cause and takes less than a minute.

Platform status: check status.zenifra.com. If there is an incident, follow it there.

Project state: in the console, the project must show Project running. If it shows Creating project, Preparing project, or Deploying, wait for the deployment; if it shows Project stopped, see Project states and check the organization credit.

Build logs: on Git projects, did the last build succeed? If it failed, the step and the reason appear in the log. See Build failures.

Application logs (available on every plan): look for errors right after startup, such as a missing variable, a database connection failure, or a module not found.

Port and address: the app must listen on 0.0.0.0 and on the same port as the Port field. This is the most common reason for a URL that does not respond while logs show no error.

Variables: confirm that every required variable exists in the project. Remember that saving variables restarts the instances.

Health check: when enabled, the route must answer 2xx quickly. A slow route or one behind a login makes the instance restart in a loop. See Health checks.

Memory: frequent restarts with memory spikes mean the plan is too small for the app. See High memory usage.

If none of this helps, contact support following the help center.

Build failures on Git projects

On GitHub and Forgejo projects, Build logs show the output of each project command up to the failure, followed by a final message with the identified cause. Review the logs and the guidance shown in the project first.

When the saved repository access no longer exists, Zenifra attempts to locate and validate the same repository again without changing its organization, name, or branch. If recovery is not possible, use Reconnect repository in the project and then start a new build. This action does not start a build automatically.

Common problems and how to investigate each scenario in the Zenifra console.

Deploy failure

"Build failed"

Check the build logs in Build logs on the project page in the console. If you prefer the terminal, use zenifra deploy watch or zenifra builds logs.

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
Build has no useful steps	Confirm `start` is configured and `build` is only set when the project really needs it
`The configured root directory does not exist in the repository.`	Check the project's Root directory field: the folder must exist on the configured branch, with a path relative to the repository root (for example, `backend` or `apps/api`)

"App crashed on startup"

Check the application logs in the console (available on every plan).

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_URL was configured manually in the HTTP project
host, port, username, password, and database name were copied correctly
the connection uses TLS as in the console URI (sslmode=verify-full for PostgreSQL); with node-postgres, remove sslmode and sslrootcert from the URI and use ssl: true, as in the database quickstart

"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 shows Project running
whether the application is writing to stdout or stderr
whether the expected message is still in the recent output: logs are read live from the instances, with no stored history

Important: application logs and build logs are different flows. Build logs shows the publication of Git projects; the project logs area shows the application after it starts.

Project states

Status	Meaning
Creating project / Preparing project	Project is being created or prepared for its first deployment
Deploying	A new version is being deployed
Project running	Project is running normally
Project has unavailable instances	One or more instances are not responding; check logs, port, and health check
We could not prepare the project	Creation or the build failed; check Build logs
Project stopped	No instance is running; project is inaccessible

Notes about Project stopped

hourly + ephemeral storage: execution billing stops
hourly + persistent storage: storage billing continues
monthly/yearly: stopping does not change the final contract value

Free plan limit reached

When you create a project, the console shows the Free plan limit reached notice once the organization has used its free resources. The message tells you which limit was reached:

Message	What to do
Your organization already uses the 2 Free plan instances. Delete a Free project or choose another plan.	Delete a project on the Free plan or select a paid plan for the new project
The Free plan allows only N more instance(s). Reduce the instances or choose another plan.	Lower the number of instances to at most N (the number shown in the notice) or select a paid plan
Your organization already uses its 2 free database projects. Delete one of them or choose another plan.	Delete a free database (PostgreSQL or Key-Value) or select a paid plan

The limits of each free plan are listed in Limits and quotas.

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 regular CNAME at the root (@)
whether all SSL validation TXT records under _acme-challenge were 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 www using an external service with HTTPS

Do not point the apex domain to IPs copied from DNS answers or old examples. Those IPs can change and are not the stable target for the project.

Need more help?

Help center and support: what to send to get a fast answer
Platform status
Email support or WhatsApp +55 (11) 5199-3013

On this page