I got an error while installing Convox

Look at the AWS Cloudformation Management Console and look for CREATE_FAILED errors on the “Events” tab.

Open a Github issue with any errors you see in these events.

I get an error when I deploy my app to Convox

During a deployment, CloudFormation will not complete an update until the ECS Services stabilize. If newly deployed processes crash or fail to pass health checks, eventually the update will time out and roll back. To figure out what’s going wrong, you can look at the app logs via convox logs to check for crashes and health check failures.

ECS events can be found in the application logs as well. Use convox logs --filter=ECS to find them.

When you know there is an issue and want to stop a deployment, you can run the convox apps cancel command. This will trigger an immediate CloudFormation rollback so you can fix the problem and try another deployment.

My app deployed but I cannot access it

Run convox apps info to find the load balancer endpoints for your application.

Run convox ps to determine if your application is booting successfully.

Run convox logs to inspect your application logs and cluster events for problems placing your container, starting your app, or registering with the load balancer.


If you’re encountering problems like any of the following:

  • deployments seem stuck in UPDATE_IN_PROGRESS CloudFormation state
  • your Rack seems stuck in converging
  • your deploys seem stuck with services continuously being killed via SIGKILL and restarted

… then you should check the ECS section of your AWS console. To do so, log into the AWS ECS web UI and click the Cluster for your Rack. You’ll be taken to a screen with a list of Services. Click on the name of the service (see note below for naming conventions). You’ll be taken to a screen with an Events tab. The events there should provide some clues about why the service isn’t stabilizing.

Service names: ECS service names are in the format <rack name>-<app name>-Service<ServiceName>-<random string>. For example, for a service defined as worker in your docker-compose.yml, an app named store on a Rack named prod, the name will be prod-store-ServiceWorker-ABC123RANDOM123XYZ.

Another note: every Rack cluster has two internal ECS services named in the format <rack name>-WebService-<random string> and <rack name>-MonitorService-<random string>. These are for the internal Rack API and agent, respectively, and you shouldn’t normally need to worry about them.

If the listed reason is Instance has failed at least the UnhealthyThreshold number of health checks consecutively, this means your app is failing its health checks. Often this is because your app is not actually listening on the port(s) specified for the service in your docker-compose.yml. Or your Rack might be missing an environment variable defined in your docker-compose.yml. It might also be an error from your application itself (check the app logs with convox logs, or use convox instances ssh to check docker logs).

Once you’ve found the reason, you can run convox apps cancel -a app_name to cancel this deployment. Once it rolls back, you can fix the error and try to deploy again.

Still having trouble?

Some good places to search are:

If you still need help, feel free to: