docker/cli · error

failed to parse as a rational number

Error message

failed to parse %v as a rational number

What it means

Thrown by ParseCPUs (opts.go:362) when big.Rat.SetString cannot parse the input as a rational number. NanoCPUs expects a decimal or fractional CPU count (e.g. 0.5, 1, 2.5); SetString fails on empty strings, letters, multiple dots, trailing operators, or any non-numeric token. The value is parsed as a ratio then scaled to nanocpus (×1e9).

Solutions

1. Pass a plain decimal CPU count: `--cpus 0.5`, `--cpus 2`, or `--cpus 2.5`.
2. Remove any unit suffixes (cores, vCPU) and surrounding whitespace.
3. If using a locale with comma decimals, convert ',' to '.' before passing.
4. Pre-validate with strconv.ParseFloat and reformat to a clean decimal string.

Example fix

// before
--cpus 2cores
// after
--cpus 2

// Pre-validate a CPU count string as a rational number before ParseCPUs.
if _, ok := new(big.Rat).SetString(strings.TrimSpace(cpu)); !ok {
    return fmt.Errorf("%q is not a valid CPU count", cpu)
}

When it happens

Trigger: Calling NanoCPUs.Set or ParseCPUs with '', 'abc', '1.2.3', '1/2/3', '0x5', '+', or a value with locale-specific separators like '1,5'. big.Rat.SetString returns ok=false at line 360, so line 362 fires.

Common situations: Setting `--cpus` with a non-numeric value, a comma decimal from a European locale, a percentage like '50%', or an empty env var. Also from templating that injects units ('2cores') or whitespace.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• invalid size
• 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/a65aa231f2a701fb. Report an issue: GitHub.

Appendix: source

Thrown at opts/opts.go:362

	*c = NanoCPUs(cpus)
	return err
}

// Type returns the type
func (*NanoCPUs) Type() string {
	return "decimal"
}

// Value returns the value in int64
func (c *NanoCPUs) Value() int64 {
	return int64(*c)
}

// ParseCPUs takes a string ratio and returns an integer value of nano cpus
func ParseCPUs(value string) (int64, error) {
	cpu, ok := new(big.Rat).SetString(value)
	if !ok {
		return 0, fmt.Errorf("failed to parse %v as a rational number", value)
	}
	nano := cpu.Mul(cpu, big.NewRat(1e9, 1))
	if !nano.IsInt() {
		return 0, errors.New("value is too precise")
	}
	return nano.Num().Int64(), nil
}

// ParseLink parses and validates the specified string as a link format (name:alias)
func ParseLink(val string) (string, string, error) {
	if val == "" {
		return "", "", errors.New("empty string specified for links")
	}
	// We expect two parts, but restrict to three to allow detecting invalid formats.
	arr := strings.SplitN(val, ":", 3)

	// TODO(thaJeztah): clean up this logic!!
	if len(arr) > 2 {

View on GitHub (pinned to 4f84911bfe)