docker/cli · error

invalid size

Error message

invalid size: %q

What it means

Thrown by MemBytes.UnmarshalJSON (opts.go:438) when the JSON token is not a properly quoted string. MemBytes memory sizes (e.g. for --memory in configs deserialized from JSON) must be a JSON string like "512m"; raw numbers, booleans, arrays, null, or unquoted tokens fail the length/quote check at line 437 before RAMInBytes is even attempted.

Solutions

1. Encode the memory value as a JSON string with a units suffix: `"memory": "512m"`.
2. If you must use bytes, still quote it: `"memory": "1073741824"` (RAMInBytes accepts bare numbers).
3. Ensure the field is non-empty and at least 3 bytes including quotes (`"0"` is the minimum valid).
4. Switch the JSON encoder to emit strings for any MemBytes/MemSwapBytes field.

Example fix

// before
{ "memory": 536870912 }
// after
{ "memory": "512m" }

// Ensure JSON memory fields are quoted strings before unmarshaling into MemBytes.
if len(raw) < 3 || raw[0] != '"' || raw[len(raw)-1] != '"' {
    return fmt.Errorf("memory must be a JSON string like \"512m\", got %s", raw)
}

When it happens

Trigger: JSON-unmarshaling into a MemBytes field with a numeric literal `512` instead of `"512m"`, an empty string `""`, an unquoted value, or a non-string JSON type (number/bool/array/object). Line 437 requires len>2 and surrounding double quotes.

Common situations: Programmatic API clients sending memory as a JSON number rather than a units-string, configs authored with `"memory": 1073741824` instead of `"memory": "1g"`, or empty/default zero values serialized as empty strings.

Related errors

• failed to parse as a rational number
• is not a valid domain
• invalid label ' ': empty name
• label ' ' contains whitespaces
• sysctl ' ' is not allowed

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

Appendix: source

Thrown at opts/opts.go:438

	val, err := units.RAMInBytes(value)
	*m = MemBytes(val)
	return err
}

// Type returns the type
func (*MemBytes) Type() string {
	return "bytes"
}

// Value returns the value in int64
func (m *MemBytes) Value() int64 {
	return int64(*m)
}

// UnmarshalJSON is the customized unmarshaler for MemBytes
func (m *MemBytes) UnmarshalJSON(s []byte) error {
	if len(s) <= 2 || s[0] != '"' || s[len(s)-1] != '"' {
		return fmt.Errorf("invalid size: %q", s)
	}
	val, err := units.RAMInBytes(string(s[1 : len(s)-1]))
	*m = MemBytes(val)
	return err
}

// MemSwapBytes is a type for human readable memory bytes (like 128M, 2g, etc).
// It differs from MemBytes in that -1 is valid and the default.
type MemSwapBytes int64

// Set sets the value of the MemSwapBytes by passing a string
func (m *MemSwapBytes) Set(value string) error {
	if value == "-1" {
		*m = MemSwapBytes(-1)
		return nil
	}
	val, err := units.RAMInBytes(value)
	*m = MemSwapBytes(val)

View on GitHub (pinned to 4f84911bfe)