Deployrr starts a container and then waits for it to run. If the container never gets there, Deployrr gives up. This page shows how to find out why and how to fix it.
Symptoms
Section titled “Symptoms”During an install, Deployrr shows a step such as one of these and does not move on:
Waiting for Traefik to start...Waiting for APP to initialize...After a while (about two minutes for Traefik) it stops with an error. For Traefik, the error is:
Timed out. Could not verify if Traefik is running.Some core apps stop with this message. Authelia, Google OAuth and TinyAuth give up after about a minute. Authentik and CrowdSec give up after about two minutes. Authentik also says “First startup can take several minutes - please be patient…”.
Timed out waiting for APP container to startHere APP is the name of the app you were installing.
After the Traefik error, Deployrr tells you to check the documentation at docs.deployrr.app and says you can generate a troubleshooting log from the Settings menu. After the “Timed out waiting for APP” error, it mentions the troubleshooting log. For CrowdSec it also points to the documentation.
Most other apps do not show a timeout. Deployrr shows “Waiting for APP to initialize…”, waits about a minute, then says “APP is running” even if the app never started. If an app is missing after an install, use the checks in the Fix section below.
Apps that need a helper container, such as a database, can stop with one of these instead. APP is the helper’s name. Deployrr then shows Dependency container startup failed.
Required dependency APP did not become healthyRequired dependency not running: APPFailed to start required dependency: APPFailed to pull image for required dependency: APPFor a helper that reports its health, Deployrr waits up to five minutes for it to become healthy, and stops sooner if Docker reports it as unhealthy. For a helper that does not report health, it waits about 30 seconds. A message that starts with “Optional dependency” is only a warning. The install carries on.
You may also see this error when you run Docker commands yourself. It comes from Docker, not Deployrr:
unknown flag: --profileThe container did not reach the running state in time. There are a few common reasons:
- The container starts and then crashes. The log shows why.
- A port the app needs is already in use by something else on your server.
- A helper container the app depends on is not running or is not healthy.
- Docker was installed before you used Deployrr, for example from snap or from your operating system’s own repositories, and it is too old. Deployrr’s app commands use Docker Compose profiles. An old Docker Compose (such as the old
docker-composewith a hyphen) does not know them and fails withunknown flag: --profile. This is general Docker behaviour, not a Deployrr message.
Deployrr does not replace a Docker it finds, and it does not check the Docker version or where Docker came from. If Docker is already there, Prerequisites > System Checks reports Docker already installed and asks “Would you like to check and update your system? (Y/n):”. That runs a normal system package update. It does not replace a snap or distro Docker. So an old Docker stays in place until you remove it. When Docker is missing, System Checks installs it from Docker’s official source.
1. Find out why the container did not start
Section titled “1. Find out why the container did not start”These are general Docker commands.
-
List all containers, including stopped ones:
Terminal window sudo docker ps -aWith the Deployrr bash aliases:
dps. To understand what the list shows, read UDMS part 13: Viewing running containers (manual setup). -
Find your container in the list. Look at the
STATUScolumn.ExitedorRestartingmeans the container crashed. Go to step 3.Up (unhealthy)means it runs but its health check fails. Go to step 3.- It is missing from the list. The container was never created. Go to step 5.
-
Read its log. Replace
CONTAINERwith the name from theNAMEScolumn. This is a value you fill in.Terminal window sudo docker logs --tail 100 CONTAINERThe last lines usually say what is wrong. Typical causes are a wrong setting, a missing file or a permission error. If Docker says
failed to create shim taskand you run in a Proxmox LXC container, see Docker fails with “failed to create shim task”. If the app uses an Rclone mount for your NAS and the files are missing, see Rclone mount fails because the folder is not empty.With the aliases:
dlogs CONTAINER. It shows the last 50 lines and follows the log; press Ctrl+C to stop.dclogsfollows the logs of all your apps. See Bash aliases. To seedocker logsused on a container, watch Bash aliases video: reading container logs at 3:56 (manual Docker Compose setup). For Traefik, see Read the Traefik logs. -
If the app uses a helper container, such as a database, check that container too. Repeat steps 2 and 3 for it. If the helper is
unhealthyor not running, fix it first. The app waits for it. -
Check for a port conflict. The log often says
address already in useorport is already allocated. ReplacePORTwith the port number the app needs. This is a value you fill in.Terminal window sudo ss -tulpn | grep ':PORT'If another program uses the port, stop that program or change the port. For port 53 and Pi-hole, see Pi-hole will not start because port 53 is already in use.
-
If the problem is not clear, run Tools > Diagnostics (“Run System Health Checks”) for a general check of your server. It needs a Basic, Plus or Pro license. See Deployrr shows “Unhealthy - Issues detected” for what each line means. Then generate a log to share when you ask for help. In Deployrr, open Settings > Logs. The menu describes it as “Generate Sanitized Deployrr Log”. See Get help on Discord for what else to include.
If the log shows image pull errors, see Docker image pulls fail.
If the app installed fine but later keeps restarting or shows unhealthy, see A container keeps restarting, is unhealthy or has exited.
2. Check which Docker you have
Section titled “2. Check which Docker you have”Do this if you saw unknown flag: --profile, or if you installed Docker yourself before you used Deployrr. These are general Linux commands.
-
Check the versions:
Terminal window sudo docker --versionsudo docker compose versionThe second command must work. If it says
docker: 'compose' is not a docker command, you have no Compose plugin. -
See whether Docker came from snap:
Terminal window snap list dockerIf it lists Docker, you have the snap version.
-
See which
dockerprogram runs:Terminal window which dockerA path that starts with
/snap/means snap Docker. -
If you use snap Docker, an old
docker-composecommand, or Docker from your OS repositories, continue with the next section. If you have a current Docker with thedocker composeplugin, your problem is one of the causes in the first section.
3. Replace the old Docker
Section titled “3. Replace the old Docker”-
Back up your Docker folder. If you have Deployrr Pro, open Tools > Backups and choose Backup (see Back up and restore your Docker folder). It stops all running containers while it works, and asks at the end whether to restart the Docker stack. Otherwise, copy the folder. Replace
YOUR_DOCKER_FOLDERwith the path of your Docker folder. This is a value you fill in. To see the path, open Prerequisites > Docker Folder in Deployrr. The recommended path is/home/USERNAME/docker.Terminal window sudo cp -a YOUR_DOCKER_FOLDER YOUR_DOCKER_FOLDER-backupCopy it to another disk if you can. A copy on the same disk does not protect you from a disk failure.
-
Remove the old Docker. This is general Linux advice. Run the command that matches how you installed Docker.
For snap:
Terminal window sudo snap remove dockerFor apt:
Terminal window sudo apt remove docker docker-engine docker.io containerd runcsudo apt autoremove -
Delete Docker’s data folder. This is the step that deletes your containers, images and volumes.
Terminal window sudo rm -rf /var/lib/docker -
Delete your Docker folder only if you want to start from nothing. Skip this step if you want to keep your app settings and data. You made the backup in step 1. Use the same path as before.
Terminal window sudo rm -rf YOUR_DOCKER_FOLDER -
Start Deployrr again.
-
Open Prerequisites > System Checks. The menu describes it as “System and Docker Checks”. If Deployrr says “It appears that System Checks were already completed. If you want to redo it, press Y/y to resume or any other key to go back:”, press
Y. -
Watch the output. Deployrr shows
Docker not installed. Installing now...and installs Docker. At the end it showsDocker is installed and running. To see System Checks install Docker, watch Deployrr 5 walkthrough: System Checks at 11:39 (shows Deployrr v5; menus differ in v6).If it shows
Docker installed but not runningorDocker installation failed, runsudo systemctl status dockerand read the message. -
Do the rest of the setup steps again if needed, then install your app.
You don’t need Settings > Reset for this. Each Prerequisites step lets you redo it. Use Reset only as a last resort.
Check it worked
Section titled “Check it worked”-
The Docker commands work:
Terminal window sudo docker --versionsudo docker compose version -
Your container shows
Upin the list:Terminal window sudo docker psWith the aliases:
dps. -
When you install the app in Deployrr again, the “Waiting for” step finishes without a timeout.

