A container keeps restarting, is unhealthy or has exited
An app that was installed and worked now does not stay up. Its container restarts again and again, reports as unhealthy, or has stopped. This page shows how to see the status, read the log, match the cause to a fix and bring the app back.
If the problem happens while Deployrr installs the app, see Deployrr times out waiting for a container to start instead.
Symptoms
Section titled “Symptoms”The status of the container shows one of these. N is a number, and the time will differ.
Restarting (N) 12 seconds agoUp 2 minutes (unhealthy)Exited (N) 3 minutes agoYou may also notice that the app’s web page does not open, or that it opens and then goes away for a while.
Most Deployrr apps are set up so Docker starts them again if they stop. If such an app crashes right after it starts, Docker starts it again, it crashes again, and you see Restarting. This is called a crash loop.
Some apps are set up not to start on their own. These are mostly media apps, such as Plex, Jellyfin, Emby, Sonarr, Radarr, Lidarr, Bazarr, Tautulli, Kavita, Komga, Navidrome and Calibre. They often use files from a NAS, so Deployrr does not start them before the share is mounted. After a crash or a server reboot, they show Exited instead of Restarting. To start them after a reboot once your Rclone mount is up, see Delay Media Apps in Mount a NAS share with Rclone. For every way to start them after a reboot, see Apps are stopped or show empty folders after a reboot.
Up ... (unhealthy) means the container runs but its own health check fails. Exited means the container stopped.
Common reasons:
- A port the app needs is used by something else.
- A folder is missing, or the app has no permission to use it.
- A NAS share or Rclone mount the app needs is not mounted.
- A helper container, such as a database, is not running or is unhealthy.
- You edited the app’s compose file or
.envvalues and made a mistake, or you edited them and did not recreate the app. - The container has no DNS or internet.
- Socket Proxy or Traefik is stopped.
1. See the status
Section titled “1. See the status”Use the terminal. This is a general Docker command:
sudo docker ps -aFind your app in the NAMES column and read its STATUS. With the Deployrr bash aliases: dps lists all containers, and dpss gives a table with name, state, status and image. To understand how the check, log and restart steps fit together, read UDMS part 13: Scenario 1, troubleshooting a container issue (manual setup).
You can also go to Tools > Stack Manager > Containers Status in Deployrr. Its Status column shows only one word, such as running, restarting or exited. It does not show unhealthy or the exit code: an unhealthy container shows as running. Stack Manager needs completed Prerequisites and a Basic, Plus or Pro license.
2. Stop the crash loop while you fix it
Section titled “2. Stop the crash loop while you fix it”A container that restarts every few seconds fills its log and can use a lot of CPU. Stop it first.
- In Deployrr, go to Apps > Manage Apps and pick the app. A restarting app usually shows “Status: Running” here. See Install and manage apps from the Apps menu for the markers.
- Choose Stop.
- Look for “APP stopped successfully”.
The same menu has Restart. One restart sometimes clears a short problem. If the app goes back to Restarting or unhealthy, stop it and read on.
Core apps such as Traefik are not in Manage Apps. Tools > Stack Manager > Stop Container lists only containers that are running at that moment, so a container in a crash loop is often missing from it. In both cases, use the terminal. This is a general Docker command. Replace CONTAINER with the container name. This is a value you fill in.
sudo docker stop CONTAINERWith the aliases: dcstop APP. Replace APP with the app’s name.
If you want the app to stay off after a restart of the whole stack, use Tools > Stack Manager > Disable. The app stays installed with its data. If the container is running, Disable asks if you want to stop it: press Y, or it keeps running until the next stack restart. Use Enable to turn it back on. To choose between the two, see Stop or Disable? in Stack Manager.
The log is still there after you stop the container.
3. Read the log
Section titled “3. Read the log”The quickest way in Deployrr: go to Apps > Manage Apps, pick the app and choose Logs. It shows the last 50 lines and keeps following. Press Ctrl+C once to stop following the log and go back to the menu. Deployrr keeps running. Pressing Ctrl+C twice closes Deployrr.
In the terminal:
-
Find the container name in the
NAMEScolumn ofsudo docker ps -a. -
Read the last lines of its log. Replace
CONTAINERwith that name. This is a value you fill in.Terminal window sudo docker logs --tail 100 CONTAINERWith the aliases:
dlogs CONTAINER. It shows the last 50 lines and keeps following. Press Ctrl+C to stop. To seedocker logsused on a container, watch Bash aliases video: reading container logs at 3:56 (manual Docker Compose setup). -
Look at the last lines before the container stopped. They usually name the problem, such as a port, a missing file, a permission error or a database that is not reachable.
Two other ways to read logs:
- Dozzle is an official app that shows Docker logs live in your browser.
- Lazydocker is in the Tools menu (“Terminal UI for Docker Management”). Use the arrow keys to pick a container and open its logs. Press
qto quit. These keys are general Lazydocker behaviour.
4. Read the health check
Section titled “4. Read the health check”Do this if the status says unhealthy. Deployrr’s Containers Status shows such a container as running, so use the terminal. These are general Docker commands.
To list every container that is unhealthy right now:
sudo docker ps --filter health=unhealthyTo see one container’s health record, replace CONTAINER with the container name:
sudo docker inspect --format '{{json .State.Health}}' CONTAINERIf this prints null, the container has no health check, and its status never says unhealthy. Only some apps have one. See Which apps have a health check. Otherwise the output shows the status (starting, healthy or unhealthy), how many checks failed in a row, and the last checks.
To read only what the last checks printed, one line each:
sudo docker inspect --format '{{range .State.Health.Log}}exit {{.ExitCode}}: {{.Output}}{{println}}{{end}}' CONTAINERBlank lines between them are normal. exit 0 means the check passed. Any other number means it failed. Read the text after it. It often says what the check could not reach, such as the app’s own port inside the container. If the app is still starting or can’t open that port, the log from step 3 usually says why.
5. Match the log to a cause
Section titled “5. Match the log to a cause”| The log or status shows | What to do |
|---|---|
address already in use or port is already allocated |
Another program holds the port. See Port already in use. |
permission denied, or a missing folder or file |
Check the folder paths the app uses. See Set your media, downloads and other folders. |
| The app needs files from your NAS and they are missing | Check that the share is mounted. See Mount a NAS share with Rclone and Rclone mount fails because the folder is not empty. |
| A helper container, such as a database, is unhealthy or not running | Repeat steps 1 to 4 for the helper. Fix it first. The app depends on it. |
password authentication failed for user or Access denied for user, after you reinstalled the app |
The app and its database no longer have the same password. See After a reinstall, the app can’t log in to its database. |
| The app talks to Docker and cannot reach it | Socket Proxy may be stopped. See Socket Proxy. |
| The page does not open and the app itself looks fine | Traefik may be the problem. See Read the Traefik logs and Traefik can’t get a Let’s Encrypt certificate. |
You edited a compose file or .env and then it broke |
Undo your edit. For the main compose file, see Docker environment setup fails with: docker-compose file is malformed. |
no such host, temporary failure in name resolution or other lookup errors |
The container has no DNS or internet. See No internet on the server or in containers after setup. |
no space left on device |
The disk is full. See When the disk is full. |
toomanyrequests or TLS handshake timeout |
The image did not download. See Docker image pulls fail. |
failed to create shim task in a Proxmox LXC container |
See Docker fails with “failed to create shim task”. |
| qBittorrent VPN is unhealthy or its web UI will not open | See qBittorrent web UI says Unauthorized or won’t open. |
For a general check of your server, run Tools > Diagnostics. It needs a Basic, Plus or Pro license. See Deployrr shows “Unhealthy - Issues detected”.
6. Start or recreate the app
Section titled “6. Start or recreate the app”After you fix the cause, bring the app back.
- In Deployrr, go to Tools > Stack Manager > Start Container.
- At “Select an app to start:”, type the number of the app and press Enter.
- Look for “APP started”.
The list shows every container that is not running, including one that is restarting. If you see “No exited containers found.”, every container is already running. Use Recreate to apply a change. You can also use Apps > Manage Apps > the app > Start and look for “APP started successfully”.
If you edited the app’s compose file or .env values, recreate the app so it picks up the change:
- Go to Tools > Stack Manager > Recreate.
- At “Select an app to recreate:”, type the number of the app and press Enter.
- Look for “APP recreated”.
With the aliases: dcstart APP and dcrec APP. Unlike the menu option, dcrec does not take the app down first.
7. Reinstall as a last resort
Section titled “7. Reinstall as a last resort”If the app still fails, reinstall it. See Reinstall an app and keep its data.
Check it worked
Section titled “Check it worked”-
The status shows
Upand does not sayRestarting,unhealthyorExited:Terminal window sudo docker ps -aWith the aliases:
dps. Containers Status in Stack Manager shows running, but it can’t tell you whether the app is healthy. -
The status still says
Upafter a few minutes. A crash loop can look fine for a few seconds. -
The app’s web page opens.
After a reinstall, the app can’t log in to its database
Section titled “After a reinstall, the app can’t log in to its database”n8n, Nextcloud, Langfuse and Supabase get new database passwords on every install, also on a reinstall. The database in appdata keeps the password it was first set up with. After a reinstall, the app and its database can stop matching. To avoid this next time, see Before you reinstall an app with generated secrets.
What you may see:
- The app shows
RestartingorExited, or its web page does not open, while its database container showsUp. - The app’s log from step 3 has a line such as
password authentication failed for user(PostgreSQL) orAccess denied for user(MariaDB). These come from the database, so the exact text depends on the app.
Your data is still there. Don’t delete the app. Pick the fix that fits:
- You have a copy of
secretsfrom before the reinstall: put the old files back and recreate, as in steps 3 and 4 of Before you reinstall an app with generated secrets. For n8n, Langfuse or Supabase, you also need the oldcomposefolder. A backup of your Docker folder has both. - n8n, and you have no copy: give the database the new password. The reinstall already wrote it to the secret file and to
n8n.yml, so you only change it inside the database.-
Show the new password. Replace
YOUR_DOCKER_FOLDERwith your Docker folder path:Terminal window sudo cat YOUR_DOCKER_FOLDER/secrets/n8n_postgresql_password -
Run step 3 of Change a database password safely with that value as
NEW_PASSWORD. Take the container, user and database for n8n from the PostgreSQL table on that page. -
Recreate the app, as in step 6.
-
- Nextcloud: after its first setup, Nextcloud reads the database password from its own
config.php. A reinstall changes neither that file nor the database, so Nextcloud normally keeps working. The reinstall shows a new admin password. Your existing Nextcloud still uses the old one, so keep using that. If you deleted the database folder but kept Nextcloud’s own folder, the two no longer match: restore your Docker folder backup, or ask on Discord. - Langfuse or Supabase, and you have no copy: their passwords are in many files and containers. A reinstall also changes other keys, such as Supabase’s API keys, so apps that use the old keys stop working. Restore your Docker folder backup, or ask on Discord.
Automatic restarts of unhealthy containers
Section titled “Automatic restarts of unhealthy containers”DeUnhealth is an official app (“Restart unhealthy containers”). It restarts unhealthy containers for you and needs Socket Proxy. In Deployrr v6, only the qBittorrent VPN app is set up for it. For other apps it does nothing unless you add a label to the app’s compose file yourself. That is an advanced, manual edit, and a reinstall may overwrite it. To see how the health check and DeUnhealth work together, watch DeUnhealth video: health check and automatic restart at 2:51 (manual Docker Compose setup with labels).
If you still need help, go to Settings > Logs (“Generate Sanitized Deployrr Log”) and press Y to continue. Deployrr shows where it saved the log. Read the file before you share it, then ask on Discord. See Get help on Discord.

