docker run fails: Cannot link to a non running container
docker: Error response from daemon: Cannot link to a non running containerShort answer
A --link needs the target container to be running at the moment you start the new one. If the database exited or never started, Docker refuses the link. Find out why it stopped, start it, and prefer a user-defined network or Compose service names over legacy links.
Fix it fast
1Find out which cause you have
List every container, including stopped ones, and see whether the one you link to is Up or Exited.
docker ps -a2Match what you see, then jump to its fix
- 1
docker ps -a shows the database as Exited.The linked container exited or crashedFix - 2
The command uses --link and the containers are on the default bridge network.--link is a legacy feature; a user-defined network does the jobFix - 3
The compose file has a links: section and the dependent service fails when the database service is not up.Compose already connects services: remove links and use the service nameFix - 4
The database container is slow to start and the web container fails once, then works on a second try.The dependent service starts before the database is healthyFix
- 1
What does the error look like?
docker: Error response from daemon: Cannot link to a non running containerCannot link to a non running container
Cause 1 of 4
The linked container exited or crashed
1Check
docker ps shows only running containers; -a also lists stopped ones. An Exited database usually left its reason in the log.
docker ps -a --filter status=exited
docker logs mysql --tail 302Fix
Fix the error the log shows (a wrong environment variable or an unusable data folder are common), then start the container before the one that links to it.
docker start mysql
docker ps3Verify
The database is listed as Up, and the dependent container starts.
docker run -d --name web --link mysql:db my-web-imageConfirmed by docs.docker.com
Cause 2 of 4
--link is a legacy feature; a user-defined network does the job
1Check
On the default bridge, name access needs --link, which Docker calls legacy. User-defined bridge networks give automatic DNS between containers by name, and a running container can be attached later.
docker network ls2Fix
Create a network, put both containers on it, and use the container name as the host name.
docker network create app-net
docker run -d --name mysql --network app-net -e MYSQL_ROOT_PASSWORD=example-password mysql:8.4
docker run -d --name web --network app-net my-web-image
# in the app: host = mysql3Verify
The web container resolves the database by name.
docker exec web getent hosts mysqlConfirmed by docs.docker.com
Cause 3 of 4
Compose already connects services: remove links and use the service name
1Check
Compose creates a default network for the project and every service is reachable by its service name; links are not needed for that, and they also add an implicit dependency between the services.
docker compose config | grep -n -B2 -A4 links2Fix
Delete links:, connect to the service name on the container port, and wait for health instead of start order.
services:
db:
image: mysql:8.4
environment:
MYSQL_ROOT_PASSWORD: example-password
healthcheck:
test: ["CMD-SHELL", "<a command that exits 0 once the database accepts connections>"]
web:
image: my-web-image
depends_on:
db:
condition: service_healthy
# app connects to host "db", port 33063Verify
Bring the stack up and check that both services stay running.
docker compose up -d
docker compose psConfirmed by docs.docker.com
Cause 4 of 4
The dependent service starts before the database is healthy
1Check
With the short form of depends_on, Compose does not wait for the dependency to be healthy.
docker compose config | grep -n -A4 depends_on2Fix
Use the long form with condition: service_healthy, together with a healthcheck on the database (see the previous cause).
depends_on:
db:
condition: service_healthy3Verify
Start from a clean state.
docker compose down
docker compose up -dConfirmed by docs.docker.com
How do I stop it coming back?
- Use a user-defined network or Compose instead of --link in anything new.
- Give databases a healthcheck and let dependants wait on service_healthy.
- Read docker logs of a container that shows Exited before starting anything that depends on it.
- Connect to other services on their container port, not on the published host port.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Servers
Docker says the network you named does not exist
Error response from daemon: network myapp not found
A container or Compose file refers to a network name the daemon does not have.
3 causes, each with a fixServers
A Docker container keeps restarting and never stays up
docker ps --filter status=restarting lists the container
A container restarts forever when its main process exits and a restart policy starts it again.
3 causes, each with a fixServers
dnf cannot install MySQL on Amazon Linux 2023
dnf cannot find a mysql-server package on Amazon Linux 2023
Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fix