Maaz Zindani

Loading the index…

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

docker compose up refuses to start because an external volume does not exist

ErrorVolume my_data declared as external, but could not be found

Short answer

A volume marked external: true is never created by Compose. If no volume with that exact name exists on the Docker host you are talking to, Compose stops with an error. List the volumes, then either create the missing one with docker volume create, fix the name: value, or drop external and let Compose own the volume.

  • Applies to Docker Engine 28, Docker Compose 2.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at what the Compose file asks for, then list the volumes the daemon really has. The name Compose looks up is the name: value if there is one, otherwise the key under volumes.

    grep -n -B1 -A3 "external" compose.yaml
    docker volume ls
  2. 2Match what you see, then jump to its fix

    1. 1docker volume ls shows no volume with the name from the Compose fileThe volume was never createdFix
    2. 2docker volume ls shows a similar volume with a prefix or another spellingThe name in the file is not the name of the real volumeFix
    3. 3The file has external: true but no one ever planned to create the volume by handYou wanted Compose to manage the volume, not an outside oneFix

What does the error look like?

  • Volume my_data declared as external, but could not be found

Cause 1 of 3

The volume was never created

1Check

Compose treats an external volume as something managed outside the application. It does not create it, and it returns an error when it is missing. A fresh server, a fresh Docker Desktop install or a pruned host all start with no such volume.

docker volume ls --filter name=my_data

2Fix

Create the volume once with the exact name the Compose file uses. docker volume create reuses a volume that already exists, so running it twice does no harm.

docker volume create my_data

3Verify

Start the stack again.

docker compose up -d

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The name in the file is not the name of the real volume

1Check

With external, name: picks the existing volume to look up, while the key under volumes stays the label your services use. Without name:, the key itself is the lookup name. A volume created by another project or by a stack that had a different name often exists under a different name.

docker volume ls
grep -n -A4 "^volumes:" compose.yaml

2Fix

Point name: at the real volume, keep the short key for the services.

volumes:
  data:
    external: true
    name: shop_postgres_data
services:
  db:
    image: postgres:17
    volumes:
      - data:/var/lib/postgresql/data

3Verify

Compose should now start without the volume error and mount the existing data.

docker compose up -d
docker compose ps

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

You wanted Compose to manage the volume, not an outside one

1Check

Compose will not create an external volume and rejects any other attribute next to external: true, except name. If the volume belongs only to this stack, the flag is the problem.

grep -n "external" compose.yaml

2Fix

Remove external: true so Compose creates the volume itself. Keep it only for a volume that was made on purpose, for example one restored from a backup.

volumes:
  data: {}

3Verify

Bring the stack up and check that the volume now exists.

docker compose up -d
docker volume ls

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Create external volumes in a setup script that runs before docker compose up, and keep that script next to the Compose file.
  • Use name: for every external volume so the lookup never depends on a project prefix.
  • Before moving a stack to a new host, copy the data first: a new host has none of the old volumes.

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

Next step

Want this handled for good?

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