Troubleshoot Apps

This page covers what goes wrong once you deploy an app. A failed build or deployment says why on its page in the dashboard and in its error field (Read a deployment and its build log), and 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.

The sidebar shows Apps under Products only while Apps is on for the platform. While it is off, the Apps pages show Page not found.

The dashboard asks the platform once in each browser tab. When Apps has been turned on since, open the dashboard in a new tab. When the dashboard cannot ask, the Apps page shows Could not reach Apps: check your connection and select Try again.

New app… and Create app are turned off

You have as many apps as you may, and the list says Delete an app to create another. Delete an app you no longer need (Delete an app).

Deploy… and Redeploy… are turned off

The app is suspended, and its page shows This app is suspended (A suspended app).

There is no Redeploy…

Nothing serves the app yet, so there is nothing to run again. Select Deploy… instead.

A deployment has no Roll back to this…

It never went live, it is the one serving now, or the app is suspended (Roll back to an earlier deployment).

Add domain… or Add variable… is turned off

The app has as many custom domains or variables as it may (Apps limits). Remove one first.

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. 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).

There is no Dockerfile at docker/Dockerfile in the repository at this commit.

The Dockerfile path does not point at a file. A path is looked for in the app's directory first, then at the root of the repository (Builds). Correct the path, or clear it to let the build choose.

Railpack could not plan this app: …

Railpack could not work out how to build or start the app from its files. The rest of the message is Railpack's reason. Check that the app's directory is right, and set the start command, or add a Dockerfile to take over the build. Railpack's documentation lists what it can build.

The image build failed (buildctl exited with 1).

A step of the build failed, such as installing packages or running the build command. The lines after the message, and the end of the build log, show which step and why (The build log). Fix the step, then deploy again.

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 60 minutes and was stopped.

A build can run for an hour. Make the build faster, or build the image yourself and create an app that runs it.

No builder took the build within 6 hours. or The builder stopped responding, and this build had already been retried once.

The platform could not run the build. Deploy again later, and contact support if it happens again.

Builds are not available on this platform yet.

The platform cannot build apps at the moment, so a git app cannot deploy a new commit. A redeploy without a rebuild, a rollback and an app that runs an image still work. Contact support for more.

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 deployment whose replicas fail in a region ends with Replicas could not start in fra: … and the reason from one of its replicas. The deployment that served the app before 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 deployment fails this way again and again, contact support.

A deployment 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 deployment tries the region again, so redeploy the app later (Redeploy).

Its error says why:

Canceled

Someone cancelled it.

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

A newer deployment 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 deployment was on its way.

The deployment did not finish within 6 hours

A deployment 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 deployment runs on new replicas, and a replica keeps nothing on its disk from one deployment to the next. Keep data in a database or in Object Storage.

Most changes reach the running replicas only with a new deployment. After you save one in the dashboard, a note under the app's header says which you need, with a Redeploy… button. Through the API, the answer to a change says redeploy_required for a redeploy, and rebuild_required for a redeploy with a rebuild (When a change applies). A change to environment variables needs a redeploy too (Apply a change).

Add a custom domain covers domains that do not verify and certificates that stay Certificate on its way. Deploy on every push covers pushes that do not deploy.

• How Apps works
• Read a deployment and its build log
• Apps limits
• Contact support from the dashboard