xds: field clientListenerResourceNameTemplate %q of authorit

Error message

xds: field clientListenerResourceNameTemplate %q of authority %q doesn't start with prefix %q

What it means

For each authority in the authorities map the library validates that, when client_listener_resource_name_template is explicitly set, it must start with xdstp://<authority_name> (URL-path-escaped). This enforces the gRFC rule that an authority-scoped listener template is namespaced under that authority. A mismatch is treated as a bootstrap parse error.

Source

Thrown at internal/xds/bootstrap/bootstrap.go:644

	// Default value of the default client listener name template is "%s".
	if c.clientDefaultListenerResourceNameTemplate == "" {
		c.clientDefaultListenerResourceNameTemplate = "%s"
	}
	if len(c.xDSServers) == 0 {
		return fmt.Errorf("xds: required field `xds_servers` not found in bootstrap configuration: %s", string(data))
	}

	// Post-process the authorities' client listener resource template field:
	// - if set, it must start with "xdstp://<authority_name>/"
	// - if not set, it defaults to "xdstp://<authority_name>/envoy.config.listener.v3.Listener/%s"
	for name, authority := range c.authorities {
		prefix := fmt.Sprintf("xdstp://%s", url.PathEscape(name))
		if authority.ClientListenerResourceNameTemplate == "" {
			authority.ClientListenerResourceNameTemplate = prefix + "/envoy.config.listener.v3.Listener/%s"
			continue
		}
		if !strings.HasPrefix(authority.ClientListenerResourceNameTemplate, prefix) {
			return fmt.Errorf("xds: field clientListenerResourceNameTemplate %q of authority %q doesn't start with prefix %q", authority.ClientListenerResourceNameTemplate, name, prefix)
		}
	}
	return nil
}

// GetConfiguration returns the bootstrap configuration initialized by reading
// the bootstrap file found at ${GRPC_XDS_BOOTSTRAP} or bootstrap contents
// specified at ${GRPC_XDS_BOOTSTRAP_CONFIG}. If both env vars are set, the
// former is preferred.
//
// This function tries to process as much of the bootstrap file as possible (in
// the presence of the errors) and may return a Config object with certain
// fields left unspecified, in which case the caller should use some sane
// defaults.
//
// This function returns an error if it's unable to parse the contents of the
// bootstrap config. It returns (nil, nil) if none of the env vars are set.
func GetConfiguration() (*Config, error) {

View on GitHub (pinned to 03255a9237)

Solutions

Set the template to start with xdstp://<authority_name>/ where <authority_name> exactly matches the map key (the library uses url.PathEscape on the key for comparison).
If you do not need a custom template, omit client_listener_resource_name_template so it defaults to xdstp://<authority_name>/envoy.config.listener.v3.Listener/%s.
Ensure the %s placeholder is preserved after the prefix if you use a custom resource path.

Example fix

// before — authority key is "my-authority" but template uses wrong host:
//   "authorities": {
//     "my-authority": { "client_listener_resource_name_template": "xdstp://other-auth/Listener/%s" }
//   }
// after:
//   "authorities": {
//     "my-authority": { "client_listener_resource_name_template": "xdstp://my-authority/Listener/%s" }
//   }

Defensive patterns

Strategy: validation

Validate before calling

// Validate authority templates match their key prefix.
func validateAuthorityTemplates(authorities map[string]json.RawMessage) error {
    for name, raw := range authorities {
        var a struct{ Tmpl string `json:"client_listener_resource_name_template"` }
        _ = json.Unmarshal(raw, &a)
        if a.Tmpl == "" { continue } // default is fine
        prefix := "xdstp://" + url.PathEscape(name)
        if !strings.HasPrefix(a.Tmpl, prefix) {
            return fmt.Errorf("authority %q template %q must start with %q", name, a.Tmpl, prefix)
        }
    }
    return nil
}

Prevention

Omit client_listener_resource_name_template unless you need a custom path, so the default applies.
When copy-pasting an authority entry, always update the xdstp:// host to match the key.
Use url.PathEscape on the authority name when constructing the prefix to match the library's comparison.

When it happens

Trigger: An authority whose clientListenerResourceNameTemplate was set to a plain name or an xdstp URI with a different authority host. For authority "foo", the template must begin with xdstp://foo/; anything else triggers this error.

Common situations: Copy-pasting a listener template from another authority without updating the host portion; using a legacy grpc:// or plain string template; URL-encoding the authority name inconsistently between the key and the prefix.

Related errors

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/d803e0d8880e1589. Report an issue: GitHub.