invalid restart policy format: no policy provided before…

Error message

invalid restart policy format: no policy provided before colon

What it means

Thrown by opts.ParseRestartPolicy when strings.Cut finds a colon but the part before it is empty, e.g. ":5". The policy name (no|always|on-failure|unless-stopped) must precede the optional ":retryCount"; a leading colon means no policy name was provided.

Solutions

Provide a valid policy name before the colon: no, always, on-failure, or unless-stopped.
If you want the default, omit --restart entirely or use the empty string (which ParseRestartPolicy treats as zero-value/no-policy).
Guard against an empty name when composing the string.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

validPolicies := map[string]bool{"no": true, "always": true, "on-failure": true, "unless-stopped": true}
name, _, _ := strings.Cut(policy, ":")
if strings.Contains(policy, ":") && !validPolicies[name] {
    return fmt.Errorf("restart policy name %q is empty or invalid", name)
}
_, err := opts.ParseRestartPolicy(policy)

Try / catch

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

Prevention

Always put the policy name before the colon.
Compose the string from validated name and integer count fields.

When it happens

Trigger: Calling opts.ParseRestartPolicy(":3"), or passing --restart=":5" on docker run/create.

Common situations: Building the restart policy string from a variable where the name component is empty (e.g. POLICY=""; docker run --restart="$POLICY:5"), or a stray leading colon typo.

Related errors

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

Appendix: source

Thrown at opts/parse.go:89

}

// ParseRestartPolicy parses a restart policy string ("name[:max-retries]")
// into a [container.RestartPolicy].
//
// Parsing is syntactic only; semantic validation is deferred to the daemon/API.
// An empty input returns a zero-value policy for backward compatibility. The
// 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)