{"record":{"id":"5e391a771cac623e","repo":"grpc/grpc-java","slug":"named-port-is-not-supported-in-grpc","errorCode":null,"errorMessage":"NAMED_PORT is not supported in gRPC.","messagePattern":"NAMED_PORT is not supported in gRPC\\.","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/XdsListenerResource.java","lineNumber":174,"sourceCode":"      throw new ResourceInvalidException(\n          \"Listener \" + proto.getName() + \" cannot have listener_filters\");\n    }\n    if (proto.hasUseOriginalDst()) {\n      throw new ResourceInvalidException(\n          \"Listener \" + proto.getName() + \" cannot have use_original_dst set to true\");\n    }\n\n    String address = null;\n    SocketAddress socketAddress = null;\n    if (proto.getAddress().hasSocketAddress()) {\n      socketAddress = proto.getAddress().getSocketAddress();\n      address = socketAddress.getAddress();\n      if (address.isEmpty()) {\n        throw new ResourceInvalidException(\"Invalid address: Empty address is not allowed.\");\n      }\n      switch (socketAddress.getPortSpecifierCase()) {\n        case NAMED_PORT:\n          throw new ResourceInvalidException(\"NAMED_PORT is not supported in gRPC.\");\n        case PORT_VALUE:\n          address = address + \":\" + socketAddress.getPortValue();\n          break;\n        default:\n          // noop\n      }\n    }\n\n    ImmutableList.Builder<FilterChain> filterChains = ImmutableList.builder();\n    Set<String> filterChainNames = new HashSet<>();\n    Set<FilterChainMatch> filterChainMatchSet = new HashSet<>();\n    int i = 0;\n    for (io.envoyproxy.envoy.config.listener.v3.FilterChain fc : proto.getFilterChainsList()) {\n      // May be empty. If it's not empty, required to be unique.\n      String filterChainName = fc.getName();\n      if (filterChainName.isEmpty()) {\n        // Generate a name, so we can identify it in the logs.\n        filterChainName = \"chain_\" + i;","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsListenerResource.java#L156-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Replace named_port with port_value (a numeric port) in the Listener's socket_address in the xDS control plane response","Fix the source YAML/JSON bootstrap config to use numeric ports, e.g. portValue: 8080 instead of name: 'grpc'","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"],"exampleFix":"# before\nsocket_address:\n  address: 0.0.0.0\n  named_port: grpc\n# after\nsocket_address:\n  address: 0.0.0.0\n  port_value: 8080","handlingStrategy":"validation","validationCode":"// Pre-validate the Listener proto before submitting/parsing\nfor (Address addr : listener.getAddressList()) {\n  SocketAddress sa = addr.getSocketAddress();\n  if (sa != null && sa.getPortSpecifierCase()\n      == SocketAddress.PortSpecifierCase.NAMED_PORT) {\n    throw new IllegalArgumentException(\n        \"Listener uses NAMED_PORT \" + sa.getNamedPort()\n        + \"; use port_value instead\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  listener = XdsListenerResource.parseServerSideListener(proto, ...);\n} catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"NAMED_PORT\")) {\n    logger.warn(\"Fix control plane: named ports unsupported by gRPC xDS\", e);\n  }\n}","preventionTips":["Always use numeric port_value in xDS Listener socket addresses","Add a control-plane lint that rejects named_port for gRPC audiences","Never copy Envoy named-port configs verbatim into gRPC xDS setups"],"tags":["xds","grpc","config-validation","listener"],"backgroundTag":"unsupported-operation","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}