This error occurs when your Docker Compose file references a volume with `external: true`, but the volume doesn't exist on your Docker host. Docker expects externally-declared volumes to be created manually before running the compose file.
When you set `external: true` on a volume in your docker-compose.yml, you're telling Docker Compose that this volume already exists and is managed outside of Compose. Instead of creating the volume automatically, Compose expects to find a volume with that exact name already on your system. This separation is intentional - external volumes are typically used for: - Sharing data between multiple Compose projects - Persisting data that should survive `docker-compose down -v` - Using volumes created with specific drivers or options If the volume doesn't exist, Docker Compose fails immediately rather than creating it, because that would violate the explicit declaration that the volume is externally managed.
The most direct fix is to create the volume that Docker Compose is looking for:
docker volume create myvolumeReplace myvolume with the exact name shown in the error message. Then run your compose file again:
docker-compose up -dList all volumes to see what exists on your system:
docker volume lsLook for your volume name. Remember that:
- Names are case-sensitive
- Compose-created volumes are prefixed with the project name (e.g., myproject_dbdata)
If you see a similar name with a prefix, that's likely the volume you need to reference.
If you don't need the volume to be externally managed, remove the external: true line and let Compose create it automatically:
Before:
volumes:
myvolume:
external: trueAfter:
volumes:
myvolume:Now docker-compose up will create the volume if it doesn't exist.
If your external volume has a different name than what you want to reference in the compose file, use the name attribute:
volumes:
db-data:
external: true
name: my-postgres-db_dataThis lets you use db-data in your service definitions while referencing the actual volume my-postgres-db_data.
If you're using Docker contexts (remote hosts, Docker Desktop vs WSL, etc.), verify you're connected to the right one:
# Show current context
docker context show
# List all contexts
docker context ls
# Switch context if needed
docker context use defaultVolumes are specific to each Docker host/context.
Some versions of Docker Compose (around v2.2.0) had a bug with external volume parsing. If you're affected, explicitly specify the name:
volumes:
myvolume:
name: myvolume
external: trueAlternatively, update Docker Compose to the latest version:
# Check version
docker compose version
# Update (on Linux)
sudo apt-get update && sudo apt-get install docker-compose-pluginUnderstanding volume lifecycle: Volumes created by Docker Compose without external: true are named {project}_{volume} and can be removed with docker-compose down -v. External volumes survive this command, which is their main benefit.
CI/CD considerations: In CI/CD pipelines, either:
1. Create volumes in a setup step before running compose
2. Remove external: true and let each pipeline run create fresh volumes
3. Use bind mounts instead of named volumes for ephemeral CI data
Multi-project volume sharing: To share a volume between projects, create it once externally, then reference it with external: true in all compose files that need it.
Volume inspection: To check a volume's details:
docker volume inspect myvolumeThis shows the driver, mount point, and labels - useful for debugging why a volume might not be found (wrong driver, etc.).
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub