hashicorp/nomad · error

invalid volume specification: '%s'

Error message

invalid volume specification: '%s'

What it means

errInvalidSpec is the canonical error of the vendored Docker Windows volume parser (windowsSplitRawSpec): the supplied spec matched none of the accepted volume/expression patterns. It names the offending spec verbatim so you can see why the regex parser rejected it.

Source

Thrown at drivers/docker/win32_volume_parse.go:77

	//    -  And can be optional

	// rxDestination is the regex expression for the mount destination
	rxDestination = `(?P<destination>((?:\\\\\?\\)?([a-z]):((?:[\\/][^\\/:*?"<>\r\n]+)*[\\/]?))|(` + rxPipe + `)|([/].*))`

	// Destination (aka container path):
	//    -  Variation on hostdir but can be a drive followed by colon as well
	//    -  If a path, must be absolute. Can include spaces
	//    -  Drive cannot be c: (explicitly checked in code, not RegEx)

	// rxMode is the regex expression for the mode of the mount
	// Mode (optional):
	//    -  Hopefully self explanatory in comparison to above regex's.
	//    -  Colon is not in the capture group
	rxMode = `(:(?P<mode>(?i)ro|rw))?`
)

func errInvalidSpec(spec string) error {
	return fmt.Errorf("invalid volume specification: '%s'", spec)
}

type fileInfoProvider interface {
	fileInfo(path string) (exist, isDir bool, err error)
}

type defaultFileInfoProvider struct {
}

func (defaultFileInfoProvider) fileInfo(path string) (exist, isDir bool, err error) {
	fi, err := os.Stat(path)
	if err != nil {
		if !os.IsNotExist(err) {
			return false, false, err
		}
		return false, false, nil
	}
	return true, fi.IsDir(), nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use the exact forms the parser accepts: [drive:]\path:[drive:]\path[:ro|rw] or a named volume with destination.
2. Reduce to at most 3 colon-separated fields; quote/escape paths with spaces before they reach the driver.
3. Test the spec with `docker run -v "<spec>" ...` on Windows to see if Docker itself accepts it.

Example fix

// before
volumes = ["C:/a/b:D:/x/y:read-only"]
// after
volumes = ["C:/a/b:D:/x/y:ro"]

// mirror the accepted patterns before calling the driver
var specRe = regexp.MustCompile(`^(?:[A-Za-z]:[\\/][^:]*|[A-Za-z0-9][A-Za-z0-9_.-]*):[^:]+(?::(ro|rw))?$`)
if !specRe.MatchString(spec) {
  return fmt.Errorf("spec %q will be rejected by docker volume parser", spec)
}

if _, err := windowsSplitRawSpec(spec, rxDestination); err != nil {
  return fmt.Errorf("docker rejected %q: %w", spec, err)
}

When it happens

Trigger: windowsSplitRawSpec called with a spec that fails rxSplit patterns: invalid drive-letter forms, more than 3 colon-separated fields, illegal characters, or mode other than ro/rw where captured.

Common situations: Paths with unquoted spaces, specs like "C:\a:D:\b:extra", mode typos ("read-only"), or UNC paths formatted incorrectly on Windows hosts.

Related errors

• not <src>:<destination> format
• volume name %q cannot be a reserved word for Windows filenam
• file '%s' cannot be mapped. Only directories can be mapped o
• running container as ContainerAdmin is unsafe; change the co
• the image does not exist: %v

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/3a214527729735e9. Report an issue: GitHub.