grpc/grpc-java · error · ResourceInvalidException

Failed to parse envoy.config.core.v3.Address: Invalid IP add

Error message

Failed to parse envoy.config.core.v3.Address: Invalid IP address or port: <ip>:<port>

What it means

XdsEndpointResource parses envoy.config.core.v3.Address protos from xDS (LDS/RDS/EDS) responses into java.net.InetSocketAddress. If InetAddresses.forString(ip) fails because the address string is not a valid IPv4/IPv6 literal, the parser wraps the failure in a ResourceInvalidException carrying the 'Invalid IP address or port' message. The xDS resource is then rejected as invalid (NACKed).

Source

Thrown at xds/src/main/java/io/grpc/xds/XdsEndpointResource.java:329

    }

    @Override
    public java.net.SocketAddress parse(Any any) throws ResourceInvalidException {
      SocketAddress socketAddress;
      try {
        socketAddress = any.unpack(Address.class).getSocketAddress();
      } catch (InvalidProtocolBufferException ex) {
        throw new ResourceInvalidException("Invalid Resource in address proto", ex);
      }
      validateAddress(socketAddress);

      String ip = socketAddress.getAddress();
      int port = socketAddress.getPortValue();

      try {
        return new InetSocketAddress(InetAddresses.forString(ip), port);
      } catch (IllegalArgumentException e) {
        throw createException("Invalid IP address or port: " + ip + ":" + port);
      }
    }

    private void validateAddress(SocketAddress socketAddress) throws ResourceInvalidException {
      if (socketAddress.getAddress().isEmpty()) {
        throw createException("Address field is empty or invalid.");
      }
      long port = Integer.toUnsignedLong(socketAddress.getPortValue());
      if (port > 65535) {
        throw createException(String.format("Port value %d out of range 1-65535.", port));
      }
    }

    private ResourceInvalidException createException(String message) {
      return new ResourceInvalidException(
          "Failed to parse envoy.config.core.v3.Address: " + message);
    }
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Fix the xDS management server config so Address.address contains a valid IPv4/IPv6 literal (e.g. 10.0.0.5 or fd00::1) instead of a hostname or placeholder.
2. If DNS names are required, resolve them to IPs on the control plane or use a resource that supports DNS endpoints per your gRPC xDS version.
3. Check the raw xDS resource dump (xDS node logs) to see the exact offending address string and correct it.
4. Verify IPv6 formatting (no zone IDs like %eth0, properly compressed) if using IPv6.

Example fix

# before (xDS/EADS endpoint config)
address: { socket_address: { address: "my-service.internal", port_value: 50051 } }

# after
address: { socket_address: { address: "10.24.3.7", port_value: 50051 } }

// before pushing endpoint config to the management server
if (!InetAddresses.isInetAddress(addr.address())) {
  throw new IllegalArgumentException("Endpoint address must be an IP literal, got: " + addr.address());
}

static boolean isValidIpLiteral(String s) {
  return s != null && !s.isEmpty() && InetAddresses.isInetAddress(s);
}

try {
  endpoint = xdsClient.watchEndpoint(...);
} catch (ResourceInvalidException e) {
  logger.error("xDS endpoint resource invalid (address parse): " + e.getMessage());
  alertControlPlaneOperator(resourceName);
}

When it happens

Trigger: An xDS management server sends an endpoint/cluster address whose socketAddress.address string is not a parseable IP literal (e.g. a hostname, empty-ish junk, or malformed IPv6) to XdsEndpointResource.parse; InetAddresses.forString throws IllegalArgumentException.

Common situations: Envoy/control-plane config using DNS names in Address.address (envoy allows hostnames via DNS resolvers, but gRPC xDS expects IP literals); typos or regional placeholders like '<ip>:<port>' from templated config; IPv6 strings with zone IDs or bad formatting.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse envoy.config.core.v3.Address: Address field
• Failed to parse envoy.config.core.v3.Address: Port value %d
• Not implemented
• unsupported ExtAuthz service type: only grpc_service is supp
• Invalid ring hash function: " + ringHash.getHashFunction()

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