istio/istio · error

fail to convert %v: %v

Error message

fail to convert %v: %v

What it means

The gateway component's buildSpec converts its values.Map into the typed apis.GatewayComponentSpec via values.ConvertMap, which round-trips the untyped map through JSON; the conversion failed for the named c.SpecName. This means the gateway component values cannot unmarshal into the spec schema, almost always a wrong field type or structure under components.ingressGateways or components.egressGateways.

Source

Thrown at operator/pkg/component/component.go:68

func (c Component) Get(merged values.Map) ([]apis.GatewayComponentSpec, error) {
	defaultNamespace := merged.GetPathString("metadata.namespace")
	var defaultResponse []apis.GatewayComponentSpec
	def := c.Default
	altEnabled := false
	if c.AltEnablementPath != "" {
		if merged.GetPathBool(c.AltEnablementPath) {
			def = true
			altEnabled = true
		}
	}
	if def {
		defaultResponse = []apis.GatewayComponentSpec{{ComponentSpec: apis.ComponentSpec{Namespace: defaultNamespace}}}
	}

	buildSpec := func(m values.Map) (apis.GatewayComponentSpec, error) {
		spec, err := values.ConvertMap[apis.GatewayComponentSpec](m)
		if err != nil {
			return apis.GatewayComponentSpec{}, fmt.Errorf("fail to convert %v: %v", c.SpecName, err)
		}
		if spec.Namespace == "" {
			spec.Namespace = defaultNamespace
		}
		if spec.Namespace == "" {
			spec.Namespace = "istio-system"
		}

		// We might copy this later by serializing and then deserializing from JSON.
		// However, `nil` Go maps get serialized to JSON `null` and desrialized to untyped `nil`.
		// When Helm tries to index from an untyped nil, it throws an error instead of returning
		// an empty value. We avoid this issue by explicitly initializing the Go map, so it gets serialized
		// into an empty JSON object `{}`.
		if spec.Label == nil {
			spec.Label = make(map[string]string)
		}
		spec.Raw = m
		return spec, nil

View on GitHub (pinned to 8dc789c5cf)

Solutions

1. Audit the gateway component block whose SpecName appears in the error and align field types with the IstioOperator API for your version
2. Correct scalar types: numbers unquoted, proper lists for ports
3. Dry-run against the CRD: kubectl apply --dry-run=server -f iop.yaml or istioctl validate
4. Start from istioctl profile dump default and re-add changes incrementally

Example fix

// before
components:
  ingressGateways:
    - name: istio-ingressgateway
      enabled: "true"
// after
components:
  ingressGateways:
    - name: istio-ingressgateway
      enabled: true

// Pre-flight: convert the gateway component map before install
if _, err := values.ConvertMap[apis.GatewayComponentSpec](gwMap); err != nil {
	return fmt.Errorf("bad gateway values: %w", err)
}

When it happens

Trigger: An IstioOperator with a malformed ingress/egress gateway entry: a string where an int or object is expected (replicaCount: "auto"), an invalid ports block, or unknown nested structure under a gateway component entry.

Common situations: Hand-written gateway values with wrong types; overlays copied from older Istio versions whose spec changed; external values merges that shift a field's type.

Related errors

• could not unmarshal: %v
• validateCIDR %s got %T, want string
• load chart: %v
• failed generating webhooks: %v
• merge inputs: %v

AI-assisted analysis of istio/istio@8dc789c5cf (2026-08-15). Data as JSON: /api/errors/e726a6a6fad0ee2d. Report an issue: GitHub.