grpc/grpc-java · error · ResourceInvalidException

NAMED_PORT is not supported in gRPC.

Error message

NAMED_PORT is not supported in gRPC.

What it means

The xDS listener parser rejects Listener resources whose socket_address uses a named port (e.g. 'http') instead of a numeric port_value. gRPC's xDS implementation requires numeric ports so it can build InetSocketAddress values deterministically. Any server-side Listener containing a NAMED_PORT specifier fails resource validation and the LDS update is NACKed.

Source

Thrown at xds/src/main/java/io/grpc/xds/XdsListenerResource.java:174

      throw new ResourceInvalidException(
          "Listener " + proto.getName() + " cannot have listener_filters");
    }
    if (proto.hasUseOriginalDst()) {
      throw new ResourceInvalidException(
          "Listener " + proto.getName() + " cannot have use_original_dst set to true");
    }

    String address = null;
    SocketAddress socketAddress = null;
    if (proto.getAddress().hasSocketAddress()) {
      socketAddress = proto.getAddress().getSocketAddress();
      address = socketAddress.getAddress();
      if (address.isEmpty()) {
        throw new ResourceInvalidException("Invalid address: Empty address is not allowed.");
      }
      switch (socketAddress.getPortSpecifierCase()) {
        case NAMED_PORT:
          throw new ResourceInvalidException("NAMED_PORT is not supported in gRPC.");
        case PORT_VALUE:
          address = address + ":" + socketAddress.getPortValue();
          break;
        default:
          // noop
      }
    }

    ImmutableList.Builder<FilterChain> filterChains = ImmutableList.builder();
    Set<String> filterChainNames = new HashSet<>();
    Set<FilterChainMatch> filterChainMatchSet = new HashSet<>();
    int i = 0;
    for (io.envoyproxy.envoy.config.listener.v3.FilterChain fc : proto.getFilterChainsList()) {
      // May be empty. If it's not empty, required to be unique.
      String filterChainName = fc.getName();
      if (filterChainName.isEmpty()) {
        // Generate a name, so we can identify it in the logs.
        filterChainName = "chain_" + i;

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Replace named_port with port_value (a numeric port) in the Listener's socket_address in the xDS control plane response
2. Fix the source YAML/JSON bootstrap config to use numeric ports, e.g. portValue: 8080 instead of name: 'grpc'
3. If the control plane cannot be changed, add a translation layer in the control plane that resolves service names to numbers before sending LDS resources

Example fix

# before
socket_address:
  address: 0.0.0.0
  named_port: grpc
# after
socket_address:
  address: 0.0.0.0
  port_value: 8080

// Pre-validate the Listener proto before submitting/parsing
for (Address addr : listener.getAddressList()) {
  SocketAddress sa = addr.getSocketAddress();
  if (sa != null && sa.getPortSpecifierCase()
      == SocketAddress.PortSpecifierCase.NAMED_PORT) {
    throw new IllegalArgumentException(
        "Listener uses NAMED_PORT " + sa.getNamedPort()
        + "; use port_value instead");
  }
}

try {
  listener = XdsListenerResource.parseServerSideListener(proto, ...);
} catch (ResourceInvalidException e) {
  if (e.getMessage().contains("NAMED_PORT")) {
    logger.warn("Fix control plane: named ports unsupported by gRPC xDS", e);
  }
}

When it happens

Trigger: A Listener proto is delivered where socket_address.port_specifier is the named_port oneof case (a service name string) rather than port_value; this is hit inside parseServerSideListener while processing each listener address via processServerSideListener.

Common situations: Control planes (or hand-written Envoy/gRPC bootstrap YAML) that use service-name ports like port: 'grpc' copied from Kubernetes service definitions; Envoy configs that legitimately allow named ports but are fed to gRPC xDS clients/servers; templating tools emitting named ports by default.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• unsupported ExtAuthz service type: only grpc_service is supp
• Invalid ring hash function: " + ringHash.getHashFunction()
• Custom LB config does not contain a JSON object
• Invalid header matcher config: [grpc-] prefixed header name
• Invalid header matcher config: header name [:scheme] is not

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