vitessio/vitess · error

failed to execute vtgate address template for %v: %w

Error message

failed to execute vtgate address template for %v: %w

What it means

This error is returned by Cluster.DiscoverVTGateAddr when the configured Go text template for rendering a single vtgate's address (c.vtgateAddrTmpl) fails to execute against the discovered vtgate protobuf. textutil.ExecuteTemplate wraps template.Template.Execute, so the underlying error is a text/template execution error (e.g. the template references a field that does not exist on vtadminpb.VTGate). The error is wrapped with %w so the root cause can be inspected with errors.Is/As.

Source

Thrown at go/vt/vtadmin/cluster/discovery/discovery_consul.go:224

	return vtgates[rand.IntN(len(vtgates))], nil
}

// DiscoverVTGateAddr is part of the Discovery interface.
func (c *ConsulDiscovery) DiscoverVTGateAddr(ctx context.Context, tags []string) (string, error) {
	span, ctx := trace.NewSpan(ctx, "ConsulDiscovery.DiscoverVTGateAddr")
	defer span.Finish()

	executeFQDNTemplate := false

	vtgate, err := c.discoverVTGate(ctx, tags, executeFQDNTemplate)
	if err != nil {
		return "", err
	}

	addr, err := textutil.ExecuteTemplate(c.vtgateAddrTmpl, vtgate)
	if err != nil {
		return "", fmt.Errorf("failed to execute vtgate address template for %v: %w", vtgate, err)
	}

	return addr, nil
}

// DiscoverVTGateAddrs is part of the Discovery interface.
func (c *ConsulDiscovery) DiscoverVTGateAddrs(ctx context.Context, tags []string) ([]string, error) {
	span, ctx := trace.NewSpan(ctx, "ConsulDiscovery.DiscoverVTGateAddrs")
	defer span.Finish()

	executeFQDNTemplate := false

	vtgates, err := c.discoverVTGates(ctx, tags, executeFQDNTemplate)
	if err != nil {
		return nil, err
	}

	addrs := make([]string, len(vtgates))

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix the vtgate address template in the cluster config so every {{...}} action matches an exported field of vtadminpb.VTGate
2. Test the template locally against a sample VTGate struct with text/template before deploying
3. If a recent Vitess upgrade introduced this, check the release notes for VTGate proto field renames and update the template

Example fix

// before (config)
vtgate_addr_template: "{{.HostName}}:{{.Port}}"
// after (fields matching vtadminpb.VTGate)
vtgate_addr_template: "{{.Hostname}}:{{.PortStr}}"

// validate the template before wiring it into the cluster
vtgateTmpl := template.Must(template.New("vtgate-addr").Parse(cfg.VtgateAddrTmpl))
var sample vtadminpb.VTGate
if err := vtgateTmpl.Execute(io.Discard, &sample); err != nil {
	return fmt.Errorf("invalid vtgate address template: %w", err)
}

addr, err := cluster.DiscoverVTGateAddr(ctx)
if err != nil {
	var tErr *template.ExecError // or use errors.As on wrapped cause
	if errors.As(err, &tErr) {
		log.Errorf("bad vtgate addr template: %v", err)
		return fallbackAddr
	}
	return err
}

When it happens

Trigger: Calling DiscoverVTGateAddr on a consul-backed discovery cluster whose vtgate_addr_template option contains field references that do not match vtadminpb.VTGate (e.g. {{.Port}} when the proto only exposes PortStr) or has invalid template actions that fail at execution time.

Common situations: Operators set a custom vtgate-addr-template in the vtadmin cluster config copied from docs for a different proto version; renaming fields in the VTGate proto breaks an old template; typos like {{.Hostname}} vs {{.Host}}.

Related errors

• failed to execute vtgate fqdn template for %v: %w
• failed to execute vtctld address template for %v: %w
• failed to execute vtctld fqdn template for %v: %w
• failed to generate vtgate consul datacenter from template: %
• failed to parse vtgate FQDN template %s: %w

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/97a96479d5887ef5. Report an issue: GitHub.