What causes "gpu request key '%s' can be specified only once" in docker/cli?

Remove the duplicate key so each appears once.

gpu request key ' ' can be specified only once

Error message

gpu request key '%s' can be specified only once

What it means

GpuOpts.Set tracks each key it has seen and rejects a second occurrence of the same key. This includes a bare integer (which implicitly counts as a "count" key), so two bare integers or count= twice will both trigger it. Each key may appear once per request.

Solutions

Remove the duplicate key so each appears once.
For multiple separate device requests, pass multiple --gpus flags rather than packing them into one.
Use the explicit key form (count=, driver=, device=) to avoid ambiguity with bare integers.
Validate/dedupe keys before calling Set if constructing the value programmatically.

Example fix

# before
docker run --gpus 'count=1,count=2' myimg

# after (two separate requests)
docker run --gpus count=1 --gpus count=2 myimg

Defensive patterns

Strategy: validation

Validate before calling

// Dedupe keys before constructing the --gpus value.
func dedupeKeys(fields []string) error {
    seen := map[string]struct{}{}
    for _, f := range fields {
        key, _, _ := strings.Cut(f, "=")
        if _, isCount := seen[key]; isCount {
            return fmt.Errorf("duplicate key %q", key)
        }
        seen[key] = struct{}{}
    }
    return nil
}

Prevention

Specify each key at most once per --gpus argument.
Use multiple --gpus flags for separate device requests.
Prefer the explicit count= form to avoid bare-integer collisions.

When it happens

Trigger: --gpus with a duplicate key, e.g. --gpus 'count=1,count=2', --gpus '1,2' (two bare counts), or --gpus 'driver=nvidia,driver=amd'.

Common situations: Combining the shorthand count and the count= key; copy-paste producing a doubled field; trying to express two GPU groups inside one --gpus argument.

Related errors

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

Appendix: source

Thrown at opts/gpus.go:50

// Set a new mount value
//
//nolint:gocyclo
func (o *GpuOpts) Set(value string) error {
	csvReader := csv.NewReader(strings.NewReader(value))
	fields, err := csvReader.Read()
	if err != nil {
		return err
	}

	req := container.DeviceRequest{}

	seen := map[string]struct{}{}
	// Set writable as the default
	for _, field := range fields {
		key, val, withValue := strings.Cut(field, "=")
		if _, ok := seen[key]; ok {
			return fmt.Errorf("gpu request key '%s' can be specified only once", key)
		}
		seen[key] = struct{}{}

		if !withValue {
			seen["count"] = struct{}{}
			req.Count, err = parseCount(key)
			if err != nil {
				return err
			}
			continue
		}

		switch key {
		case "driver":
			req.Driver = val
		case "count":
			req.Count, err = parseCount(val)
			if err != nil {

View on GitHub (pinned to 4f84911bfe)