invalid restart policy format: maximum retry count must be…

Error message

invalid restart policy format: maximum retry count must be an integer

What it means

Thrown by opts.ParseRestartPolicy when a retry count is present after the colon but strconv.Atoi fails to parse it as an integer. Only on-failure style policies use a retry count, and it must be a base-10 integer (negative values pass here but may be daemon-rejected).

Solutions

Use a plain integer for the retry count, e.g. on-failure:5.
If the count comes from a variable, validate it is numeric before composing the string.
Drop the retry count if you only want the on-failure policy with daemon defaults.

Example fix

// before
_, _ = opts.ParseRestartPolicy("on-failure:abc")
// after
_, _ = opts.ParseRestartPolicy("on-failure:5")

Defensive patterns

Strategy: validation

Validate before calling

_, count, ok := strings.Cut(policy, ":")
if ok && count != "" {
    if _, err := strconv.Atoi(count); err != nil {
        return fmt.Errorf("retry count %q must be an integer", count)
    }
}
rp, err := opts.ParseRestartPolicy(policy)

Try / catch

rp, err := opts.ParseRestartPolicy(policy)
if err != nil {
    return err
}

Prevention

Use strconv.Atoi on the count before composing the string.
Avoid floats or units in the retry count.

When it happens

Trigger: Calling opts.ParseRestartPolicy("on-failure:abc"), or --restart=on-failure:5x, or a retry value with spaces or units.

Common situations: Typing the retry count as a float ("on-failure:5.0"), appending units/letters, or interpolating a non-numeric variable into the count position.

Related errors

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

Appendix: source

Thrown at opts/parse.go:96

// retry count, if set, must be an integer (negative values are allowed here
// but may be rejected by the daemon).
func ParseRestartPolicy(policy string) (container.RestartPolicy, error) {
	if policy == "" {
		// For backward compatibility, do not set an explicit default ("no"),
		// as older daemons may not support it.
		return container.RestartPolicy{}, nil
	}

	name, count, ok := strings.Cut(policy, ":")
	if ok && name == "" {
		return container.RestartPolicy{}, errors.New("invalid restart policy format: no policy provided before colon")
	}

	var retryCount int
	if count != "" {
		c, err := strconv.Atoi(count)
		if err != nil {
			return container.RestartPolicy{}, errors.New("invalid restart policy format: maximum retry count must be an integer")
		}
		retryCount = c
	}

	return container.RestartPolicy{
		Name:              container.RestartPolicyMode(name),
		MaximumRetryCount: retryCount,
	}, nil
}

View on GitHub (pinned to 4f84911bfe)