docker/cli · error

invalid mode specified

Error message

invalid mode specified: %v

What it means

Thrown by ConfigOpt.Set (config.go:62) when the `mode` field cannot be parsed as an unsigned 32-bit integer. The file mode for the mounted config is parsed with strconv.ParseUint(val, 0, 32), which accepts decimal or 0-prefixed octal/hex. Non-numeric, out-of-range, or malformed mode values produce this wrapped error.

Solutions

1. Use numeric mode, preferably octal with leading 0: `--config source=c,mode=0440`.
2. If you want decimal, ensure it fits in uint32 and represents the intended bits.
3. Avoid symbolic notation; this parser does not understand 'rwx'.
4. Validate with `strconv.ParseUint(val, 0, 32)` before constructing the flag.

Example fix

// before
--config source=appconf,mode=r--r-----
// after
--config source=appconf,mode=0440

// Validate the config mode as a uint32 (base 0 → octal with 0 prefix) before Set.
if _, err := strconv.ParseUint(modeVal, 0, 32); err != nil {
    return fmt.Errorf("mode %q must be a numeric (octal with 0-prefix) uint32", modeVal)
}

When it happens

Trigger: Passing `--config source=c,mode=abc`, `mode=r--r--r--` (symbolic notation), `mode=99999999999` (overflow), or `mode=0xZZ`. ParseUint with base 0 fails, and the error is wrapped at line 62.

Common situations: Using symbolic chmod notation ('rw-r--r--') instead of numeric, forgetting the leading 0 for octal (`mode=644` is parsed as decimal 644 = octal 0o1204), or passing a permission string from another tool.

Related errors

• invalid field ' ' must be a key=value pair
• invalid field in config request
• invalid field
• invalid protocol value
• invalid publish mode value

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/a6522c0116df6291. Report an issue: GitHub.

Appendix: source

Thrown at opts/swarmopts/config.go:62

		key, val, ok := strings.Cut(field, "=")
		if !ok || key == "" {
			return fmt.Errorf("invalid field '%s' must be a key=value pair", field)
		}

		// TODO(thaJeztah): these options should not be case-insensitive.
		switch strings.ToLower(key) {
		case "source", "src":
			options.ConfigName = val
		case "target":
			options.File.Name = val
		case "uid":
			options.File.UID = val
		case "gid":
			options.File.GID = val
		case "mode":
			m, err := strconv.ParseUint(val, 0, 32)
			if err != nil {
				return fmt.Errorf("invalid mode specified: %v", err)
			}

			options.File.Mode = os.FileMode(m)
		default:
			return fmt.Errorf("invalid field in config request: %s", key)
		}
	}

	if options.ConfigName == "" {
		return errors.New("source is required")
	}
	if options.File.Name == "" {
		options.File.Name = options.ConfigName
	}

	o.values = append(o.values, options)
	return nil
}

View on GitHub (pinned to 4f84911bfe)