This guide will give you some advice on how to troubleshoot and fix an app that did not deploy successfully.
»Types of deploy failures
App deployments typically fail for 2 main reasons:
- The code in your repository fails to build correctly
- The running app fails to come up correctly
Adaptable provides information on the App Status page to help debug each issue.
The first step in debugging any deploy issue is to go to the App Status page and check the
How to Fix This App box.
This box will show all the failed builds and containers along with tips on how to repair the error.
If the App Status page shows
Error Deploying App but there are no failed builds or containers, another kind of failure occurred in the deploy.
View Deploy Logs to identify the cause of the failure, or contact support if it is not clear how to fix the failure.
»Troubleshooting build failures
Each deployment template build the code from the source repository you created. This build process creates an image that Adaptable will run. If this build fails, the app deploy (or update) will fail, and the app will show up in the failed state in the Dashboard.
To begin troubleshooting this problem, navigate to the App Status page by clicking on the name of the app on the Dashboard.
Then click the
View Build Logs button in the
How to Fix This App box.
Look through the build logs to see why your app build failed to begin diagnosing and fixing the problem.
»Reproducing build failures in dev
If the fix for the build failure is not obvious from the logs, the first step is to try to reproduce the build failure in your development environment.
You can do this by manually running the build steps on your local dev setup.
The build steps Adaptable runs can be found by clicking the
View Build Logs button in the
How to Fix This App box.
The specific mechanics of reproducing errors in dev, and addressing the problem, will depend on the template, tools, and languages used in your app.
If the failure can be reproduced in the dev environment, you can now work on resolving the specific build issue via web search, Stack Overflow, or your other favorite resources.
If the failure cannot be reproduced in the dev environment, it may be related to specific settings in the build environment that are not replicated in the dev environment, such as environment variables.
You can see the build environment variables that are set by looking at the
Templates will show most environment variables that are set for builds here.
Sometimes, the template documentation may have other information about how the template interacts with your app that you might find helpful. You can find the template docs by clicking the name of the template on the App Status page.
»Troubleshooting container deploy failures
After a particular container image is built from the source code in your repository, Adaptable will deploy this image to the Adaptable Container Service.
When this happens, your application may fail to start correctly, or might start but fail to listen on the port specified by the
PORT environment variable set during app startup.
The best way to diagnose and fix deploy failures is to look at the container run-time logs and then reproduce the failure in your dev environment.
When there is a failure to deploy a container successfully, the
How to Fix This App box will appear.
This box will give you helpful tips on how to fix the problem based on the specific error message and template your app is using.
For all container deploy failures, there will be a button to
View Container Logs.
Click this button to view the logs and diagnose the cause of the failure.
»Reproducing container failures in dev
The next step is to reproduce the container failure in dev.
The specifics of this will depend heavily on your specific application, its dependencies and configuration.
If you need to connect to resources provided by Adaptable, such as the database, you can get connection information on the
You can then set this information in the relevant environment variables for your app.
The template documentation may contain more information on how Adaptable will set these variables, and which variables will be set. You can find the template documentation by clicking the name of the template on the App status page.
If you cannot reproduce the problem in your dev environment, feel free to contact support for help.
»Failure to listen on port
One of the most common errors, especially for newly created apps is:
The container failed to start and listen on the port defined by the PORT environment variable
You will see this error in the
How to Fix This App box on the App Status page, as well as in the deploy logs.
This error occurs when the app fails to listen on the port specified in the
PORT environment variable, which is automatically set by Adaptable when your app starts.
This is not necessarily a fixed port number, and so your code needs to examine the PORT environment variable and listen for requests here.
The best way to understand why this failure occurs is to start your application in the dev environment but set the PORT environment variable before doing so.
For example, if the command to start your app in the dev environment is
npm start, you can do:
# PORT=2345 npm start
Then, try to connect to your app on this port via your browser or command line tool (e.g.,
Remember, the deploy template documentation may have better information on how to listen on the port in the
PORT variable, so don't forget to consult that documentation as well.
If you cannot connect, it could be that your app always listens to some default port configured for the dev environment.
If you cannot resolve this error, feel free to contact support so we can help you debug the problem.
»Troubleshooting other failures
There may be other failures that arise in the course of deploying your app, or using your app.
Most errors that are caused by problems with Adaptable will request that you contact support for help. The other most common class of errors are runtime errors that occur after the app starts successfully, but fails when used. For these errors, navigate to the
Resources tab, and click
View Logs for the appropriate container.
The logs generated by your application are here, which you can use to troubleshoot problems. However, there are several error messages that you may see in your logs that may not come directly from your application.
»No available instance
Under certain circumstances, you may see the message:
The HTTP request was aborted because there was no available instance. See https://adaptable.io/docs/troubleshooting-deploy#no-available-instance
This message occurs when there is no underlying resource (yet) available to service the request. This can happen for several reasons, most of which are related to delay in spinning up instances to address the current load. Specific reasons include:
- A large increase in traffic causing existing instances to be busy.
- A large cold startup time (i.e., the time it takes to start the first instance after the app has been idle for some time).
- Long request processing times in your app that forces many new instances to be started.
- Reaching the maximum number of container instances for this app (which is controlled by your plan).
- This should be associated with a 429 response code
- Transient factors in the Adaptable Container Service.
Feel free to contact support if you need help resolving this error.
»503 response error
If your service takes too long to respond or responds with a malformed HTTP response (i.e., one that is illegal according to the HTTP protocol) you will see the following message in your logs:
The request failed because either the HTTP response was malformed or connection to the instance had an error or exited unexpectedly.
If you are using a framework to process HTTP requests, this error is likely due to a timeout or out of memory error. In the case that your container instance has hit the memory limit defined by your App's chosen plan, there should be a log message to this effect. If the response is timing out, you can increase the request timeout in the framework you are using. If this does not help, contact support to see if Adaptable's request timeout is the issue. Regardless, support will help you find the root cause and resolve the issue.
»504 request timeout
If your app takes too long to respond to a request, you will see the following message:
The HTTP request was terminated because the app took longer than the maximum request timeout. You can request a timeout increase by contacting Adaptable support.
Please contact support if you need to increase the timeout. Otherwise reduce the processing time your app needs to respond to these requests.
If you cannot successfully deploy your app, please contact support and we'll help you fix things.