When a deploy fails

A deploy that fails does not take your app down. The version that was working stays live while you fix things, so a bad push costs you the new version and nothing else.

When a build stops, the console tells you why in plain language rather than handing you the last line of a log. This page is that list — what each message means, and the usual fix.

The messages you might see

"Your app is missing a dependency it needs to run"

Something your code imports is not in the project's dependency file. Usually the same cause: a package was installed on the machine the app was written on and never added to package.json, requirements.txt, Gemfile or the equivalent.

The console names the imports it could not resolve. Add them to the dependency file, commit, and push.

"Your app needs a setting that was not available while it was being built"

Some frameworks read configuration while they build, not only while they run — so a variable that is set correctly can still be missing at the moment the build needs it.

Add it on the Environment tab and redeploy. See Environment variables.

"Your code has a type error, so the build stopped before it finished"

A TypeScript error. The console names the file and the line. Nothing is wrong with the platform here — the same build would fail on your own machine.

If you are in a hurry and the error is in code you are not shipping, the quickest honest fix is to correct the type, not to switch type-checking off.

"Your app's build needed more memory than its server could give it"

The build itself ran out of memory — nothing in your code is wrong, and there is nothing to change on your side. Large apps can need more memory to build than to run.

We are alerted when this happens and make room for the build; once we have, deploy again. Builds are already given memory in proportion to your app's size. If you set Node's heap size yourself in your build script (for example NODE_OPTIONS=--max-old-space-size=4096 next build), that is used instead — put it there rather than on the Environment tab, which also applies to the running app.

"Your app built, but it didn't produce the files we were going to publish"

The build finished without an error and wrote nothing where we were going to look for it. Almost always one of two things:

• the framework is configured to build for a different host, and has written output in that host's layout rather than a plain folder of files; or
• the output folder is not the conventional one for that framework.

Both are fixed in your build configuration rather than here.

"Your app deployed but isn't responding at its web address"

The build succeeded and the app started, but nothing answered when we asked for a page. The usual causes, in order:

1. The app is listening on a fixed port. It has to use the port we give it — read it from the environment rather than hard-coding one.
2. The app is listening on localhost only. Inside a container that means "nobody can reach me". Bind to all interfaces.
3. The app takes longer to start than we wait for.

"Your app stopped unexpectedly after starting"

It built, it started, and then it exited. This is your app's own runtime error — a missing variable it only reads on startup, a database it cannot reach, a crash on the first request. The runtime log is where the reason is. See Logs.

"We couldn't work out how to build this app, so no build was started"

We read your repository and could not tell how to build it, so we stopped before building anything. The message says what to do next:

• "This repository contains several apps … pick one as the app folder." Your repository holds more than one app, for example a front end, a server/ folder and shared code. Open the app's Build settings, choose the folder that holds the app you want to deploy, and deploy again.
• "Add a Dockerfile to your repo." We found no language or framework we build. A Dockerfile tells us exactly how to build and start your app.

When you create a new app, the wizard checks this first. If the deploy would fail this way, the wizard stops on its Review step and creates nothing, so no app or database is left behind.

"We couldn't download your code from GitHub"

We could not get your code, so nothing was built. The message names the cause. The commonest ones are a branch that no longer exists, and a repository that Roar's GitHub connection no longer has access to. Check both on GitHub, then deploy again.

"We couldn't fetch the commit this deploy was for" usually means a push rewrote history (a force-push, for example). Deploy again to build the latest commit on your branch.

"Something went wrong on our side before your app started building"

The deploy failed before any build log existed. Nothing in your code caused this. Deploy again, and if it keeps happening, tell us.

"The deploy failed for a reason we could not classify"

We could not match the build output to anything we recognise. The build log is complete and unedited on the Logs tab — and this is the case worth sending to us, because a failure we cannot name is usually one we should be able to.

Where to look

• Build log — everything from fetching your code to producing the image. Read this for a failure that happened before your app started. A deploy that stopped before building has only a line or two here, or nothing at all. In that case the message at the top of the app's page is the whole story.
• Runtime log — what your app has printed since. Read this for a crash, a bad response, or anything that worked locally and does not here.

Both are on the Logs tab, and both are described in Logs.

If none of this helps

Mail cloud@roar-ai.com with the app's name and roughly when the deploy ran. You do not need to copy the log out — we can see it.

We would rather hear about a deploy you could not explain than have you work around it. A failure that is hard to read is a bug on our side, even when the cause turns out to be in the code.