docker/cli · error

failed to read gpu options

Error message

failed to read gpu options: %w

What it means

The options= field is itself parsed as CSV via csv.Reader. If that read fails — typically an unterminated quote or otherwise malformed CSV inside the options value — the csv error is wrapped here. The surrounding GPU value parsed fine; only the nested options CSV is broken.

Solutions

1. Quote each CSV field properly: options="k=v","k2=v2".
2. Avoid commas inside option values, or quote them per RFC 4180.
3. Pre-parse the options substring with encoding/csv in a test to catch quoting errors early.
4. Simplify by omitting options if unused.

Example fix

# before
docker run --gpus 'options=a=1,b=2' myimg   # ambiguous

# after (proper CSV quoting)
docker run --gpus 'options="a=1","b=2"' myimg

// Pre-parse the options= value as CSV to catch quoting errors early.
func validOptionsCSV(val string) error {
    r := csv.NewReader(strings.NewReader(val))
    _, err := r.Read()
    return err
}

When it happens

Trigger: --gpus 'options=...' where the options value is malformed CSV, e.g. an unmatched double-quote, a stray quote, or illegal quoting of embedded commas.

Common situations: Forgetting to quote key=value pairs that contain commas; unbalanced quotes when passing options; shell-quoting mistakes.

Related errors

• invalid count ( ): value must be either "all" or an integer
• gpu request key ' ' can be specified only once
• unexpected key ' ' in
• could not parse public key from file
• invalid spec

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

Appendix: source

Thrown at opts/gpus.go:79

		}

		switch key {
		case "driver":
			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)

View on GitHub (pinned to 4f84911bfe)