docker/cli · error

unexpected key ' ' in

Error message

unexpected key '%s' in '%s'

What it means

GpuOpts.Set only recognizes the keys driver, count, device, capabilities, options (plus a bare integer shorthand for count). Any other key=value or unknown token reaches the default branch and is rejected with the offending key and field echoed back.

Solutions

1. Use only valid keys: driver, count, device, capabilities, options.
2. Check spelling against the documented grammar.
3. Use a bare integer for count shorthand (--gpus 2).
4. If constructing the value in code, validate keys against the whitelist before calling Set.

Example fix

# before
docker run --gpus 'gpus=2' myimg

# after
docker run --gpus 'count=2,driver=nvidia' myimg

var gpuKeys = map[string]bool{"driver": true, "count": true, "device": true, "capabilities": true, "options": true}

func validGpuFields(fields []string) error {
    for _, f := range fields {
        key, _, ok := strings.Cut(f, "=")
        if !ok {
            key = "count" // bare integer shorthand
        }
        if !gpuKeys[key] {
            return fmt.Errorf("unexpected gpu key %q", key)
        }
    }
    return nil
}

When it happens

Trigger: --gpus with an unknown key, e.g. --gpus 'foo=bar', --gpus 'gpus=2', or a misspelled valid key like --gpus 'capabilties=compute'.

Common situations: Typo in a key; assuming a key exists that the GPU request grammar does not define; copy-paste from a different tool's syntax.

Related errors

• invalid count ( ): value must be either "all" or an integer
• gpu request key ' ' can be specified only once
• invalid spec
• failed to read gpu options
• invalid bind address format

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

Appendix: source

Thrown at opts/gpus.go:83

			req.Driver = val
		case "count":
			req.Count, err = parseCount(val)
			if err != nil {
				return err
			}
		case "device":
			req.DeviceIDs = strings.Split(val, ",")
		case "capabilities":
			req.Capabilities = [][]string{append(strings.Split(val, ","), "gpu")}
		case "options":
			r := csv.NewReader(strings.NewReader(val))
			optFields, err := r.Read()
			if err != nil {
				return fmt.Errorf("failed to read gpu options: %w", err)
			}
			req.Options = ConvertKVStringsToMap(optFields)
		default:
			return fmt.Errorf("unexpected key '%s' in '%s'", key, field)
		}
	}

	if _, ok := seen["count"]; !ok && req.DeviceIDs == nil {
		req.Count = 1
	}
	if req.Options == nil {
		req.Options = make(map[string]string)
	}
	if req.Capabilities == nil {
		req.Capabilities = [][]string{{"gpu"}}
	}

	o.values = append(o.values, req)
	return nil
}

// Type returns the type of this option

View on GitHub (pinned to 4f84911bfe)