What causes "invalid type %T for string list" in docker/cli?

invalid type %T for string list

Error message

invalid type %T for string list

What it means

Thrown by transformStringList, the transformer for string-list fields (e.g. `cap_add`, `dns`, `tmpfs` short form). It accepts a single string or a `[]any`; any other type (map, int, bool) is rejected.

Solutions

Use a list: `cap_add: [ALL]`.
A single string is also accepted: `cap_add: ALL`.

Example fix

# before
web:
  dns:
    server: 8.8.8.8
# after
web:
  dns:
    - 8.8.8.8

Defensive patterns

Strategy: type-guard

Validate before calling

func validateStringList(field string, v any) error {
    switch v.(type) {
    case string, []any:
        return nil
    default:
        return fmt.Errorf("%s must be string or list, got %T", field, v)
    }
}

Type guard

func isStringOrList(v any) bool {
    switch v.(type) {
    case string, []any:
        return true
    }
    return false
}

Prevention

String-list fields accept a single string or a list of strings — not a map.
When in doubt, use the list form.
Validate rendered output.

When it happens

Trigger: A string-list field is given a mapping or scalar non-string, e.g. `cap_add: { add: ALL }` or `dns: 8.8.8.8` (int-ish).

Common situations: Using a map where a list is required; forgetting the list bracket for a single value.

Related errors

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

Appendix: source

Thrown at cli/compose/loader/loader.go:800

}

var transformStringOrNumberList TransformerFunc = func(value any) (any, error) {
	list := value.([]any)
	result := make([]string, len(list))
	for i, item := range list {
		result[i] = fmt.Sprint(item)
	}
	return result, nil
}

var transformStringList TransformerFunc = func(data any) (any, error) {
	switch value := data.(type) {
	case string:
		return []string{value}, nil
	case []any:
		return value, nil
	default:
		return data, fmt.Errorf("invalid type %T for string list", value)
	}
}

var transformHostsList TransformerFunc = func(data any) (any, error) {
	hl := transformListOrMapping(data, ":", false, []string{"=", ":"})

	// Remove brackets from IP addresses if present (for example "[::1]" -> "::1").
	result := make([]string, 0, len(hl))
	for _, hip := range hl {
		host, ip, _ := strings.Cut(hip, ":")
		if len(ip) > 2 && ip[0] == '[' && ip[len(ip)-1] == ']' {
			ip = ip[1 : len(ip)-1]
		}
		result = append(result, fmt.Sprintf("%s:%s", host, ip))
	}
	return result, nil
}

View on GitHub (pinned to 4f84911bfe)