Troubleshoot the Apps API

This page covers what goes wrong once you deploy an app. A failed build or release says why in its error field (Read a release and its build log with the Apps API), and on its release on the app's Releases tab in the dashboard. The messages below are the ones it shows. The errors you can hit while you create or change something are on that task's own page.

Your apps are on the App Deployment list in the sidebar, one row each, as a Web service (Container Apps and Apps in App Deployment). There is no separate Apps page any more, and a link to an app's old page opens its deployment's page.

While Apps is off for the platform, the list has no web services, static sites or hybrid sites, and every Apps request answers 404.

When every Apps request answers 404 with {"detail": "Not Found"}, Apps is turned off on the platform. No request reaches it until it is turned on again.

When one app answers 404 with App not found, the app belongs to another account or organization, or it was deleted, or the ID is a game server's or a database's, which the Apps API does not reach. An organization's app answers only under /api/v1/orgs/{org_slug}/apps, so check that you use the organization's path, and that you are a member of the organization.

git could not fetch main from https://github.com/example/web-shop.

The branch does not exist, or the repository is private and the app has no access token that can read it. Check the branch name, and save a token that can read the repository (Change the settings). The lines after the message are git's own output.

The repository host github.com does not resolve.

The host name in the repository address does not exist in DNS. Check the address.

The repository host git.example.com resolves to 10.0.0.5, which is not a public address.

The repository is on a private network. The build reaches only public hosts, so move the repository to one.

main has moved past commit 9f2c1e7b4a6d, and github.com does not serve an older commit by its id. Deploy the branch again.

You deployed a commit that is no longer the tip of its branch, and the git host does not serve older commits by their ID. Deploy the branch, or deploy the commit from a branch whose tip it is.

The repository token cannot be read on this platform. Save the token again in the app's settings.

The platform can no longer read the saved access token. Save the token again, then deploy.

The app directory apps/web is not in the repository at this commit.

The app's directory does not exist in the commit you deployed. Check its spelling and case, or clear it to build from the root (Change the settings).

Dockerfiles are not built on the platform. Build the image in your CI and deploy it as a container image.

The app names a Dockerfile path, and Dockerfiles are not built. Build the image in your CI, push it where anyone can pull it, and create an app that runs it (Dockerfile? Deploy a container image). Or clear dockerfile_path and let the build detect the framework.

The build could not work out the framework

The app's directory holds none of the files a framework is detected from, such as package.json, requirements.txt or go.mod. Check that the directory is right, or set framework and the install, build and start commands (Frameworks we build).

A command failed

The install or build command exited with an error. The end of the build log shows the command and its output (The build log). Fix it, then deploy again. A build that runs out of memory stops with the command it was running; the build container has 4 GB.

The build variable API_KEY cannot be read on this platform. Save it again.

The platform can no longer read a variable's saved value. Set its value again (A value that cannot be read).

The build ran for more than an hour

A build can run for an hour, and is then stopped. Make the build faster, or build the image in your CI and create an app that runs it.

The build waits and does not start

On older terms, your plan runs a set number of builds at once, and the rest wait their turn (What your plan includes). An app billed by use has no such limit. A spend limit that is reached also holds new builds (Spend limits). A build that has not started within 6 hours fails. Deploy again later, and contact support if it happens again.

The app did not pass its health check within 10 minutes. Health check on /: the connection failed

Nothing answered on the replica's port. The app must listen on the port in its PORT variable, on every interface (0.0.0.0), and start within 10 minutes (What your app must do).

Health check on /healthz: HTTP 404

The app answers, but not with a status from 200 to 399 on the health check path. Correct the path (Change the settings), or make the app answer on it.

Health check on /healthz: no answer within 5 seconds

The app took longer than 5 seconds to answer. Make the health check path answer quickly, without calling slow services.

A release whose replicas fail in a region ends with Replicas could not start in fra: … and the reason from one of its replicas. The live release keeps serving.

Replicas could not start in fra: No app node in fra has room for another replica of this deployment

The region has no room for the app's replicas at the moment. Try again later, choose other regions, run fewer replicas in each region, or choose a smaller size (Change the settings).

The replica's server did not finish installing within 20 minutes

Placing the replica and pulling its image took more than 20 minutes. A large image takes longer to pull, so make it smaller if you can, then deploy again.

The replica's server could not be created, could not be installed or could not be started

The platform could not start the replica. We replace it on our own. When a release fails this way again and again, contact support.

A release of an app that runs in every region goes live without a region that failed, and its error names the region, such as Left out sin: No app node in sin has room for another replica of this deployment. The app serves from its other regions. The next release tries the region again, so redeploy the app later (Redeploy).

Its error says why:

Canceled

Someone cancelled it.

A newer release was promoted or A newer release is already serving

A newer release went live first, which is expected when you deploy twice close together.

The app was suspended or The app was deleted

The app stopped being active while the release was on its way.

The release did not finish within 6 hours

A release has 6 hours to go live. Look at its replicas for the reason (Replicas), then deploy again.

Taken out of service after 3 failed health checks in a row. Health check on /healthz: HTTP 500

A running replica failed three health checks in a row. It stopped taking requests, and we started a replacement in its region. Check what the app does on the health check path, fix it and deploy.

When every replica of an app fails, they all keep serving so the app is not left with none.

Each release runs on new replicas, and a replica keeps nothing on its disk from one release to the next. Keep data in a database or in Object Storage.

Most changes reach the running replicas only with a new release. Regions and replica counts do not: they apply at once, with no redeploy (Choose locations and scaling). Through the API, the answer to a change says redeploy_required for a redeploy, and rebuild_required for a rebuild (When a change applies). In the dashboard, a notice at the top of the app's page says Redeploy to apply your changes, or Rebuild to apply your changes when the change is to the build, and has the button that starts the release. A change to environment variables needs a new release too (Apply a change).

Add a custom domain with the Apps API covers domains that do not verify and certificates that stay pending. Deploy on every push covers pushes that do not deploy.

• How the Apps API runs an app
• Read a release and its build log with the Apps API
• Apps API limits
• Deploy, promote and roll back releases
• Contact support from the dashboard