grpc/grpc-java · error · XdsInitializationException

client_listener_resource_name_template: '${clientListnerTemp

Error message

client_listener_resource_name_template: '${clientListnerTemplate}' does not start with ${prefix}

What it means

When parsing the 'authorities' section of a bootstrap, the per-authority 'client_listener_resource_name_template' must be an xDS-style template beginning with the 'xdstp://' scheme, the authority name, and a trailing slash (prefix = "xdstp://<authority>/"). Templates not starting with that prefix are rejected with XdsInitializationException.

Source

Thrown at xds/src/main/java/io/grpc/xds/client/BootstrapperImpl.java:224

    Map<String, ?> rawAuthoritiesMap =
        JsonUtil.getObject(rawData, "authorities");
    ImmutableMap.Builder<String, AuthorityInfo> authorityInfoMapBuilder = ImmutableMap.builder();
    if (rawAuthoritiesMap != null) {
      logger.log(
          XdsLogLevel.INFO, "Configured with {0} xDS server authorities", rawAuthoritiesMap.size());
      for (String authorityName : rawAuthoritiesMap.keySet()) {
        logger.log(XdsLogLevel.INFO, "xDS server authority: {0}", authorityName);
        Map<String, ?> rawAuthority = JsonUtil.getObject(rawAuthoritiesMap, authorityName);
        String clientListnerTemplate =
            JsonUtil.getString(rawAuthority, "client_listener_resource_name_template");
        logger.log(
            XdsLogLevel.INFO, "client_listener_resource_name_template: {0}", clientListnerTemplate);
        String prefix = XDSTP_SCHEME + "//" + authorityName + "/";
        if (clientListnerTemplate == null) {
          clientListnerTemplate = prefix + "envoy.config.listener.v3.Listener/%s";
        } else if (!clientListnerTemplate.startsWith(prefix)) {
          throw new XdsInitializationException(
              "client_listener_resource_name_template: '" + clientListnerTemplate
                  + "' does not start with " + prefix);
        }
        List<?> rawAuthorityServers = JsonUtil.getList(rawAuthority, "xds_servers");
        List<ServerInfo> authorityServers;
        if (rawAuthorityServers == null || rawAuthorityServers.isEmpty()) {
          authorityServers = servers;
        } else {
          if (rawAuthorityServers.size() > 1 && !enableXdsFallback) {
            rawAuthorityServers = ImmutableList.of(rawAuthorityServers.get(0));
          }
          authorityServers = parseServerInfos(rawAuthorityServers, logger);
        }
        authorityInfoMapBuilder.put(
            authorityName, AuthorityInfo.create(clientListnerTemplate, authorityServers));
      }
      builder.authorities(authorityInfoMapBuilder.buildOrThrow());
    }

View on GitHub (pinned to 64daddc1f3)

Solutions

Rewrite the template as "xdstp://<authority-name>/envoy.config.listener.v3.Listener/%s", matching the authority key it is declared under.
Remove the per-authority client_listener_resource_name_template to use the default (prefix + Listener/%s).
Cross-check the authority name in the template against the key under 'authorities'.

Example fix

// before
"authorities": { "foo.com": { "client_listener_resource_name_template":
  "envoy.config.listener.v3.Listener/%s" } }
// after
"authorities": { "foo.com": { "client_listener_resource_name_template":
  "xdstp://foo.com/envoy.config.listener.v3.Listener/%s" } }

Defensive patterns

Strategy: validation

Validate before calling

String tpl = authorityCfg.get("client_listener_resource_name_template");
String prefix = "xdstp://" + authorityName + "/";
if (tpl != null && !tpl.startsWith(prefix)) {
  throw new IllegalStateException(
      "authority " + authorityName + " template must start with " + prefix);
}

Prevention

Per-authority templates must be "xdstp://<that-authority>/..." — never reuse the top-level template format.
Generate authority config programmatically from the authority name to guarantee the prefix.
Review multi-authority bootstrap configs carefully; this field differs per authority.

When it happens

Trigger: Setting client_listener_resource_name_template for an authority to a plain resource path (e.g. "envoy.config.listener.v3.Listener/%s") without the xdstp://<authority>/ prefix, or using a prefix for a different authority.

Common situations: Copying the top-level client_listener_resource_name_template (which uses different rules) into an authority entry; mixing templates across authorities; hand-editing multi-authority bootstrap configs for TD/federation setups.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/6d3c6faf1f020457. Report an issue: GitHub.