docker compose up refuses to start because an external volume does not exist
Volume my_data declared as external, but could not be foundShort 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.
Fix it fast
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 ls2Match what you see, then jump to its fix
- 1
docker volume ls shows no volume with the name from the Compose fileThe volume was never createdFix - 2
docker 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
The 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
- 1
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_data2Fix
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_data3Verify
Start the stack again.
docker compose up -dConfirmed by docs.docker.com
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.yaml2Fix
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/data3Verify
Compose should now start without the volume error and mount the existing data.
docker compose up -d
docker compose psConfirmed by docs.docker.com
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.yaml2Fix
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 lsConfirmed by docs.docker.com
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
Servers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 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 fix