# Troubleshooting

> The messages you may see when a build, a start or a domain fails, what each one means and what to do.

Find the message you see, or the thing that goes wrong. The message of a failed deployment is on its page under **Deployments**. Lines from the running app are under **Logs**.

A quick way to find most of these before you deploy: [Check your app](https://arrangic.com/docs/check-your-app.md).

## The build fails

| Message or sign | What to do |
| --- | --- |
| There is no package.json at the top of the repository | Your app is in a folder. Set the **Root directory** in the [build settings](https://arrangic.com/docs/build-settings.md#root-directory) |
| The root directory ... is not in the repository | The folder name is wrong, or it is not on this branch. Correct the **Root directory** |
| Branch ... was not found | The branch was renamed or removed. Choose the branch under **Settings** |
| A command is "not found" during the build, `tsc` for example | The tool is not in your `package.json`: on your machine it is installed for every project. Add it to `devDependencies`. See [Packages your build needs](https://arrangic.com/docs/build-settings.md#packages-your-build-needs) |
| The install fails because the lockfile does not match | Run the install on your machine, commit the lockfile, push |
| The install fails in a `prepare` or `postinstall` script | The script calls a tool that is not installed. Make it skip the tool when it is missing |
| The build took longer than 30 minutes and was stopped | Make the build shorter, or build less |
| The repository is larger than 1 GB | Remove large files from the repository |

## The new version does not start

The deployment fails and the previous version stays online.

| Message | What it means | What to do |
| --- | --- | --- |
| ... exited right after starting with the new image | The app crashed when it started | Read the runtime log. Often a variable is missing, or the start command is wrong |
| ... did not start with the new image | The start command did not run | Check the **Start command** |
| ... started but its health check did not pass | Nothing listened on the port in time | Listen on `process.env.PORT` and on `0.0.0.0`, within 2 minutes |
| The start command could not be run | The command does not exist in the app | Check the **Start command**. A tool from `devDependencies` is not in the running app |

In the runtime log you may also see:

- **Waiting for the app to listen on port N.** The app has started but does not listen yet.
- **The app refused a connection ... make sure it listens on 0.0.0.0:N, not only on 127.0.0.1.** Your server listens on `localhost`. See [Port and address](https://arrangic.com/docs/frameworks/express.md#port-and-address).

## A deploy command fails

The running app is not changed. See [Deploy commands](https://arrangic.com/docs/deploy-commands.md#if-one-fails).

## The app is slow on the first request

It was asleep and had to start. Switch on **Keep one replica always on**, or **Wake up fast**, under **Scaling**. See [Sleep and wake](https://arrangic.com/docs/sleep-and-wake.md).

## Sessions or files disappear

The memory and the disk of the app are temporary. They are lost when the app is deployed or restarted, and when it sleeps. Keep data in a database or a store outside the app. See [Data and files](https://arrangic.com/docs/frameworks/express.md#data-and-files).

## A scheduled job does not run

The app was asleep. Jobs run only while the app runs. Switch on **Keep one replica always on**.

## A changed variable has no effect

Variables reach the app with the next deployment. Choose **Redeploy now** in the notice at the top of the app.

## The app keeps crashing

| Line in the runtime log | What to do |
| --- | --- |
| The app exited with code N | Read the lines above it for the error your app printed |
| The app ran out of memory and was stopped | Choose a larger size under [Scaling](https://arrangic.com/docs/scaling.md) |
| The app kept crashing: after N restarts it is not started again | Fix the error and deploy again |

## A page says "No app at this address"

The request used a hostname the app does not know.

- **A domain of yours.** Add it under **Domains** and wait until it is verified.
- **The platform URL.** It is switched off. Switch it on under **Domains**, or use your own domain.

## A domain stays at "Waiting for DNS"

- Compare the records at your DNS provider with the ones under **Domains**: type, name and value.
- Check the name. The dashboard shows the part in front of your root domain: `@` for the root domain itself, `www` for `www.example.com`. A few DNS providers want the full hostname instead.
- Switch off a proxy or CDN in front of the record.
- DNS changes can take a while to spread. The check runs every few minutes.

## Deploy does nothing

- **The app is paused.** Choose **Resume**, then deploy.
- **Deploy on push is off.** Switch it on under **Settings**, or choose **Deploy**.
- **The push went to another branch.** Only the branch of the app deploys.

## Still stuck

Write to support. The address is on the [contact page](https://arrangic.com/contact). Name the app and copy the message you see, with its reference if it shows one.

---

This page on the site: https://arrangic.com/docs/troubleshooting  
All pages of the documentation: https://arrangic.com/llms.txt