Maaz Zindani

Loading the index…

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

A Docker named volume points at a host folder and the container will not start

Errorfailed to mount local volume

Short answer

A named volume built on the local driver passes its options straight to the Linux mount call. If the device path in those options does not exist, the mount fails with no such file or directory. Inspect the volume, create the folder it names, and remove and recreate the volume if its stored path is wrong.

  • Applies to Docker Engine 28, Docker Compose 2, Docker Desktop 4, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the options stored on the volume. The device value is the host path Docker tries to mount; check that this exact path exists where the Docker daemon runs.

    docker volume inspect my-data
    ls -ld /srv/my-data
  2. 2Match what you see, then jump to its fix

    1. 1docker volume inspect shows Options with type none, o bind and a device path, and ls says that path is missing.The device folder in the volume options does not existFix
    2. 2Mounts denied or cannot start service, on macOS or Windows, for a folder outside the default shared locations.Docker Desktop cannot see the host pathFix

What does the error look like?

  • failed to mount local volume
  • no such file or directory

Cause 1 of 2

The device folder in the volume options does not exist

1Check

With the local driver, Docker hands the options on to the Linux mount call. A bind source has to exist already, and mount reports a path with a missing part as ENOENT, which is the text no such file or directory.

docker volume inspect my-data --format '{{ .Options }}'
test -d /srv/my-data && echo exists || echo missing

2Fix

Create the folder on the host. The volume keeps the options it was created with, so if the stored device path is wrong, stop the containers that use it, delete the volume and create it again with the right path.

sudo mkdir -p /srv/my-data
docker volume rm my-data
docker volume create --driver local \
  --opt type=none --opt o=bind --opt device=/srv/my-data my-data

3Verify

Start a throwaway container with the volume and list it.

docker run --rm -v my-data:/data alpine ls -la /data

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

Docker Desktop cannot see the host path

1Check

On Docker Desktop the daemon runs in a Linux VM. Only the folders listed under Settings, Resources, File sharing are visible to it; by default these are /Users, /Volumes, /private, /tmp and /var/folders on Mac.

ls -ld /Users/me/projects/my-data

2Fix

Move the data folder under a shared location, or add its parent folder in the File sharing list and apply the change. Then recreate the volume.

docker volume rm my-data
docker volume create --driver local \
  --opt type=none --opt o=bind --opt device=/Users/me/projects/my-data my-data

3Verify

Run a container that lists the volume.

docker run --rm -v my-data:/data alpine ls -la /data

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Create the host folder in the same script that creates the volume, before the first container uses it.
  • Use a plain named volume when the host never has to read the files; bind options are only for a fixed host location.
  • Keep the volume options in the Compose file so they are written down, and remove the old volume when you change them.

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.