vitessio/vitess · error

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

Error message

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

What it means

discoverVTGates sets each vtgate's FQDN by executing c.vtgateFQDNTmpl against the vtgate when executeFQDNTemplate is enabled and the template is non-nil. If textutil.ExecuteTemplate fails, the whole discovery returns this wrapped error. It is raised once per vtgate inside the loop, so the message names the specific vtgate whose FQDN could not be rendered.

Source

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

			case c.vtgateCellTag:
				cell = value
			case c.vtgatePoolTag:
				pool = value
			}
		}

		vtgate.Cell = cell
		vtgate.Pool = pool

		if keyspaces, ok := entry.Service.Meta[c.vtgateKeyspacesToWatchTag]; ok {
			vtgate.Keyspaces = strings.Split(keyspaces, ",")
		}

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

		vtgates[i] = vtgate
	}

	return vtgates, nil
}

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

	executeFQDNTemplate := true

	return c.discoverVtctld(ctx, tags, executeFQDNTemplate)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix the vtgate fqdn template to reference only fields that exist on vtadminpb.VTGate
2. Validate the template compiles and executes with template.Must plus a sample struct in a scratch program
3. If FQDN templating is not needed, remove the fqdn template from the cluster config

Example fix

// before
vtgate_fqdn_template: "{{.Service}}.{{.Namespace}}.svc"
// after
vtgate_fqdn_template: "{{.Name}}.svc.cluster.local"

if cfg.VtgateFQDNTmpl != "" {
	fqdnTmpl := template.Must(template.New("vtgate-fqdn").Parse(cfg.VtgateFQDNTmpl))
	var sample vtadminpb.VTGate
	if err := fqdnTmpl.Execute(io.Discard, &sample); err != nil {
		return fmt.Errorf("invalid vtgate fqdn template: %w", err)
	}
}

gates, err := cluster.DiscoverVTGates(ctx)
if err != nil {
	if strings.Contains(err.Error(), "fqdn template") {
		log.Errorf("bad vtgate fqdn template: %v", err)
		return nil, err
	}
	return nil, err
}

When it happens

Trigger: Calling DiscoverVTGates / DiscoverVTGateAddrs / discoverVTGate on a consul cluster configured with vtgate_fqdn_template containing invalid syntax or field references not present on vtadminpb.VTGate.

Common situations: FQDN template like "{{.Name}}.svc.cluster.local" where the field is actually FQDN/Hostname on the proto; template syntax typo (unclosed {{ ); upgrade changed proto field names.

Related errors

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

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