Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker run fails: Cannot link to a non running container

Errordocker: Error response from daemon: Cannot link to a non running container

Short 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.

  • Applies to Docker Engine 28, Docker Compose 2, MySQL 8.4 image, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 -a
  2. 2Match what you see, then jump to its fix

    1. 1docker ps -a shows the database as Exited.The linked container exited or crashedFix
    2. 2The 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. 3The 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. 4The 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

What does the error look like?

  • docker: Error response from daemon: Cannot link to a non running container
  • Cannot 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 30

2Fix

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 ps

3Verify

The database is listed as Up, and the dependent container starts.

docker run -d --name web --link mysql:db my-web-image

Confirmed by docs.docker.com

Did this fix it?

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 ls

2Fix

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 = mysql

3Verify

The web container resolves the database by name.

docker exec web getent hosts mysql

Confirmed by docs.docker.com

Did this fix it?

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 links

2Fix

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 3306

3Verify

Bring the stack up and check that both services stay running.

docker compose up -d
docker compose ps

Confirmed by docs.docker.com

Did this fix it?

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_on

2Fix

Use the long form with condition: service_healthy, together with a healthcheck on the database (see the previous cause).

depends_on:
  db:
    condition: service_healthy

3Verify

Start from a clean state.

docker compose down
docker compose up -d

Confirmed by docs.docker.com

Did this fix it?

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:

Related fixes

Servers

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.