Troubleshooting Deployments

Understand deployment failures and unresponsive applications

Your app doesn't respond to the public URL or your service is in an abnormal state and you're wondering why? You will find below a few common errors and failures which might happen.

When you investigate failures, you should pay attention to the state of the nodes composing your service. When you deploy a service, Koyeb will start one or more nodes depending on your configuration. All these nodes will be health-checked before routing production traffic to them.

Unhealthy node

Nodes are detected as unhealthy when health checks fail.

More precisely, every time a node is booted to support your service, all the network ports you decided to open will be health-checked every XX secs. If any of these ports doesn't respond in XX sec after the boot of the node, the node will be declared as unhealthy.

Unresponsive network ports usually come from one of these reasons:

  1. Network port configuration issue: the network port you selected is not the one your service is listening on
  2. Binding on localhost instead of if your application is bound to localhost or, nobody outside your container can reach your application. Ensure your application is bound to to make it reachable
  3. Service configuration issue: your service is not starting due to an application-specific issue like a missing environment variable or a connection issue to another service
  4. Service failure: your service might fail at startup or when it's processing requests due to a lack of memory or temporary storage

If you don't understand why a node is unhealthy, check the logs of the node.


Click Logs. You can filter logs per node, we will display the last 1000 lines for each node.

Slow service

Slow service response time is usually related to a lack of resource or a contention for external resources like a database.