Some of the links shared in this post are affiliate links. If you click on the link and make a purchase, we will receive an affiliate commission at no additional cost to you.
Sometimes it can happen that the following error message appears when starting the Docker Compose Stack, natively or via Portainer:
Failed to deploy a stack: service "docker" refers to undefined volume mnt/docker: invalid compose projectThe error “Failed to deploy a stack: service ‘docker’ refers to undefined volume mnt/docker: invalid compose project” occurs if a volume is defined in a Docker Compose file that is not specified correctly or refers to a directory that does not exist.
Error description
The error usually occurs because the Docker Compose file(docker-compose.yml) contains a volume path or volume label that is either:
- isnot formatted correctly,
- does not exist or
- wasnot clearly defined.
The error message indicates that the volume mnt/docker is not defined or referenced correctly. This means that Docker Compose cannot resolve or create the specified path.
Possible causes
- Missing leading slash: The path to the volume does not start with a
/. This causes Docker to interpret the path as a relative path, which is incorrect. - Directory does not exist: The specified directory path
(/mnt/docker) does not exist on the host system. - Typing error or incorrect syntax: A typing error in the path or in the compose file leads to an incorrect definition.
- Volume definition is missing or incorrectly placed: If a named volume is used, it must be defined under
volumes:in the compose file.
Solution steps
1. check and correct the volume path
- The path in the Docker Compose file should be absolute and correct.
- Make sure that the path exists on the host system.
Example:
services:
my_service:
image: my_image:latest
volumes:
- /mnt/docker:/data
Make sure that /mnt/docker exists. If not, create it with the command:
sudo mkdir -p /mnt/docker2. check the path for typing errors
Pay attention to possible typing errors in the volume specification and correct them.
Wrong:
No leading “/”
volumes:
- mnt/docker:/data
Correct:
Leading “/”
volumes:
- /mnt/docker:/data 3. use named volumes correctly
If you want to use named volumes, you must define these explicitly under volumes: in the Compose file:
Example for named volumes:
version: '3'
services:
app:
image: my_image:latest
volumes:
- mydata:/data
volumes:
mydata:
driver: local
driver_opts:
type: none
o: bind
device: /mnt/docker
The named volume mydata is defined here and linked to the path /mnt/docker. The device field should point to an existing directory.
4. make sure that the directories exist and have the correct permissions
Check the permissions and the existence of the directory. Docker must be able to access the specified path and write to it:
ls -ld /mnt/dockerShould ensure that the path exists and is readable/writable. If not, set the authorizations accordingly:
sudo chmod 755 /mnt/docker
sudo chown $USER:$USER /mnt/docker5. check the Docker Compose version
Make sure that the Docker Compose file used matches the installed Docker Compose version. Use version 3 or higher to use named volumes and other advanced features.
The error “service ‘docker’ refers to undefined volume mnt/docker” occurs when volumes are not defined correctly or the paths are incorrect. The problem can usually be resolved by carefully checking and correcting the Docker Compose file and the directory structure and ensuring that named volumes are defined correctly.
