create mydata/: "mydata/" includes invalid characters for a local volume name
appears when the left side of -v is a relative folder name such as
mydata/. Docker reads it as the name of a named volume, and a slash is not
allowed in one. Start the path with ./ or give the full path.
On Windows, -v ./mydata:/data, -v ${PWD}\mydata:/data and
--mount type=bind,source=./mydata,... all mounted the folder in this test. The
message itself says the rest: "use absolute path".
The error
PS> docker run --rm --name fix9-run-vol -v mydata/:/data alpine ls /data
docker: Error response from daemon: create mydata/: "mydata/" includes invalid characters for a local volume name, only "[a-zA-Z0-9][a-zA-Z0-9_.-]" are allowed. If you intended to pass a host directory, use absolute path
...
Run 'docker run --help' for more information
Why it happens
The source part of -v source:target is either a host path or a volume name.
mydata/ did not start with ./, a drive letter or a slash, so the
engine tried to create a local volume called mydata/ and refused the name: the
allowed pattern in the message, [a-zA-Z0-9][a-zA-Z0-9_.-], has no slash.
A plain name without a slash is accepted, but as a volume name. In the test
-v fix9-run-mydata:/data created a named volume and mounted it, and the container
saw an empty folder instead of host files: ls -la /data listed
only . and .., and docker volume ls then showed a new
local volume of that name. If your files seem to have vanished inside the
container, check docker volume ls for a volume named after your folder.
The fix
Each of these mounted the host folder and printed the file inside it, run from the folder that holds mydata:
PS> docker run --rm --name fix9-run-vol -v ./mydata:/data alpine cat /data/hello.txt
hello from the host
PS> docker run --rm --name fix9-run-vol -v ${PWD}\mydata:/data alpine cat /data/hello.txt
hello from the host
PS> docker run --rm --name fix9-run-vol -v "$(Get-Location)\mydata:/data" alpine cat /data/hello.txt
hello from the host
PS> docker run --rm --name fix9-run-vol --mount type=bind,source=./mydata,target=/data alpine cat /data/hello.txt
hello from the host
The ./ form is the shortest. ${PWD} and $(Get-Location)
are PowerShell variables for the current folder, so they give Docker a full Windows path.
--mount is longer, and its keys
(type, source, target) make clear that a bind mount is
meant.
How it was reproduced
On Windows 11 with Docker Desktop, engine and client 29.9.3, from Windows PowerShell 5.1, with
the cached alpine image. A scratch folder held a subfolder mydata
with one text file. -v mydata/:/data gave the error above; the four forms in the
fix printed the file. The container, volume and folder names are the test's own, and the
named volume was removed afterwards.
Frequently asked
- Can I use a relative path with docker run -v?
- Yes, if it starts with ./ as in -v ./mydata:/data. A bare name such as mydata/ is read as a volume name and refused because of the slash.
- Why is my bind mount empty inside the container?
- One cause: the source was a plain name such as mydata, so Docker created an empty named volume with that name instead of mounting your folder. docker volume ls shows it. Use ./mydata or a full path.
- How do I mount the current folder in Docker on Windows PowerShell?
- Use -v ./mydata:/data, or -v ${PWD}\mydata:/data, or --mount type=bind,source=./mydata,target=/data. All three mounted the folder in this test.
More decoded errors in the Fixes category. Bind mounts and named volumes side by side: Docker for .NET developers, bind mounts and volumes.