vitessio/vitess · error

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

Error message

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

What it means

Cluster.DiscoverVtctldAddr renders the vtctld address from c.vtctldAddrTmpl via textutil.ExecuteTemplate. When template execution fails (invalid field access or malformed action against the vtctld protobuf), the error is wrapped with the vtctld value and returned to the caller.

Source

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

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

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

	executeFQDNTemplate := false

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

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

	return addr, nil
}

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

	executeFQDNTemplate := false

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

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

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Correct the vtctld address template so its actions match the vtctld proto fields
2. Compile-check the template with template.Must at startup so bad templates fail fast
3. Render the template against a sample vtctld struct locally to confirm the output

Example fix

// before
vtctld_addr_template: "{{.GrpcAddress}}"
// after
vtctld_addr_template: "{{.Hostname}}:{{.PortStr}}"

vtctldTmpl := template.Must(template.New("vtctld-addr").Parse(cfg.VtctldAddrTmpl))
var sample vtadminpb.Vtctld
if err := vtctldTmpl.Execute(io.Discard, &sample); err != nil {
	return fmt.Errorf("invalid vtctld address template: %w", err)
}

addr, err := cluster.DiscoverVtctldAddr(ctx)
if err != nil {
	log.Errorf("vtctld addr template failed: %v", err)
	return defaultVtctldAddr, nil
}

When it happens

Trigger: Calling DiscoverVtctldAddr when the vtctld address template in the cluster config references fields that do not exist on the vtctld proto message or has invalid template syntax.

Common situations: Config copied from a vtgate template but applied to vtctld whose proto differs; typo in field name; template expecting a port field that was renamed.

Related errors

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

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