🚨 Docker Error Guide: 'invalid volume specification' — Fix Mount Syntax

Overview

invalid volume specification is a parse-time error: Docker cannot make sense of the -v/--volume string you passed before it even tries to mount anything. The format of the volume argument is wrong — a missing field, an extra or misplaced colon, a relative path where an absolute one is required, or a Windows drive letter confusing the colon-delimited parser.

The literal error names the offending spec:

docker: Error response from daemon: invalid volume specification: '/data:ro'.

On Windows hosts the drive-letter colon is a frequent trigger:

docker: Error response from daemon: invalid volume specification: 'C:\Users\me\app:/app:rw': invalid mount config for type "bind": invalid mount path.

Symptoms

• docker run/docker create fails instantly with invalid volume specification and the container is never created.
• The same command works on a colleague’s machine but not yours (Windows vs Linux path differences).
• A Compose volumes: entry rejected as malformed on docker compose up.
• The error names a string that is missing a container path, or has too many/few colons.

Common Root Causes

• Missing the container path — -v /host/data alone (bind mounts need source:destination), or a stray option with no destination like -v /data:ro.
• Relative host path — bind-mount sources must be absolute (-v ./data:/app is invalid via -v; only --mount or Compose resolve relatives).
• Too many colons — extra colon or an options field in the wrong position: -v /host:/container:ro:z:extra.
• Windows drive-letter parsing — C:\path:/container where the parser splits on the drive colon; needs the correct Docker Desktop path form.
• Named volume vs bind confusion — treating a name like a path, or vice versa; data:/app (named volume) vs /data:/app (bind).
• Unquoted spaces or trailing colon — a path with spaces or a trailing : breaking field parsing.

Diagnostic Workflow

Reproduce and read exactly which spec Docker rejected — the quoted string is the clue:

docker run --rm -v /data:ro alpine true
# invalid volume specification: '/data:ro'  <- no container path

Count the colon-delimited fields; a Linux bind mount is source:destination[:options] (2–3 fields):

echo '/host/data:/app:ro' | awk -F: '{print NF" fields"}'

Confirm the host source is an absolute path:

realpath ./data     # -v needs the absolute result, not the relative form

Prefer the explicit --mount syntax, which fails with a clearer message and forbids ambiguity:

docker run --rm --mount type=bind,source="$(pwd)"/data,target=/app,readonly alpine ls /app

For Compose, validate the file before running:

docker compose config

Example Root Cause Analysis

A developer’s start script failed on every machine with:

invalid volume specification: '/data:ro'

The intent was a read-only bind mount, but the destination path was missing — -v /data:ro was parsed as source /data, destination ro, which is not an absolute container path, so the whole spec was rejected. The author had dropped the container target.

The fix was to supply all three fields explicitly: -v /srv/data:/app/data:ro. To prevent the class of typo entirely, the team switched the script to the self-documenting long form, --mount type=bind,source=/srv/data,target=/app/data,readonly, which names each field and errors clearly if one is missing.

Prevention Best Practices

• Prefer --mount over -v in scripts — its key=value fields are self-documenting and fail with precise messages.
• Always give absolute host paths for bind mounts, or use Compose which resolves relatives against the file location.
• Include the container destination every time; a bind mount without a target is always invalid.
• On Windows, use Docker Desktop’s path form and avoid raw drive-letter colons in -v.
• Distinguish named volumes from binds: a leading / (or ./) means a bind mount; a bare name means a named volume.
• Validate Compose with docker compose config in CI to catch malformed volumes: entries before deploy.

Quick Command Reference

docker run -v /abs/host:/container:ro img        # correct 3-field bind
docker run --mount type=bind,source=/abs,target=/c,readonly img
docker run --mount type=volume,source=mydata,target=/data img
docker volume create mydata                      # named volume
docker compose config                            # validate compose volumes
realpath ./relative/path                          # resolve to absolute

Conclusion

invalid volume specification is a syntax error, not a mount failure — Docker rejected the string before mounting. Check that a bind mount has an absolute source and a container destination, count the colon fields, and mind Windows drive letters. Switching from -v to the explicit --mount form eliminates most of these mistakes and gives clearer errors. For runtime mount failures after the spec parses, see the invalid mount config for type bind guide and the full Docker guides.