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.
tip
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.
Click 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 Settings tab.
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.
tip
Many modern builds rely on external network resources to build successfully. For example, most JavaScript projects will depend on the NPM package registry. These resources can become intermittently inaccessible due to network and service outages between Adaptable and the service. For these intermittent errors, you can force Adaptable to retry the deployment via a manual deployment update.
»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 accept network connections, usually because the app fails 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 Resources tab.
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 either failed to start or failed to accept network connections.
You will see this error in the How to Fix This App box on the App Status page.
In the deploy logs you will see
The container failed to start and listen on the port defined by the PORT environment variable.
This error occurs when the app fails to listen on the port specified in the PORT environment variable.
There are two ways that the PORT variable gets its value.
»Adaptable Sets PORT
The first is to have Adaptable automatically set the PORT environment variable when your app starts.
In this case, the port is not necessarily fixed and so your code needs to examine the PORT environment variable and listen for requests there.
If you are relying on Adaptable to set the value of PORT automatically, you can diagnose this failure by starting your application in your dev environment while setting the PORT environment variable.
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., curl, wget, etc.).
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.
»PORT is Set in App Settings
The other way is to explicitly set the PORT environment variable in your App's Runtime Environment settings.
In this case, you can try to understand why this failure occurs by starting your application in your dev environment.
Then, try to connect to your app on the value you set for PORT via your browser or command line tool (e.g., curl, wget, etc.).
If your app listens on a fixed port, like 3000, make sure you tell Adaptable about this port by setting the PORT variable in the Runtime Environment section of your app's settings.
»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.
»Getting help
If you cannot successfully deploy your app, please contact support and we'll help you fix things.