grpc/grpc-java · error · ResourceInvalidException

Failed to parse envoy.config.core.v3.Address: Address field

Error message

Failed to parse envoy.config.core.v3.Address: Address field is empty or invalid.

What it means

XdsEndpointResource.validateAddress rejects envoy.config.core.v3.SocketAddress messages whose address string is empty, since a network address is mandatory to build an InetSocketAddress. The failure is wrapped as ResourceInvalidException prefixed 'Failed to parse envoy.config.core.v3.Address:'. The xDS resource is treated as invalid and NACKed.

Source

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

        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. Set the required SocketAddress.address field on every endpoint in the xDS configuration at the management server.
2. Audit generated/templated endpoint configs for unset variables that render an empty address.
3. Inspect the NACKed resource in control-plane/ADS logs to find which locality/endpoint lacks the address.
4. Upgrade the control plane if it has a known bug emitting empty addresses for unhealthy or draining endpoints.

Example fix

# before (EDS endpoint missing address)
endpoints:
- lb_endpoints:
  - endpoint: { address: { socket_address: { port_value: 50051 } } }

# after
endpoints:
- lb_endpoints:
  - endpoint: { address: { socket_address: { address: "10.0.1.12", port_value: 50051 } } }

// reject endpoints with empty addresses before publishing to xDS
for (LbEndpoint ep : assignment.getEndpointsList()) {
  SocketAddress sa = ep.getEndpoint().getAddress().getSocketAddress();
  if (sa.getAddress().isEmpty() || sa.getPortValue() == 0) {
    throw new IllegalArgumentException("Endpoint missing address: " + ep);
  }
}

static boolean hasCompleteAddress(SocketAddress sa) {
  return sa != null && !sa.getAddress().isEmpty();
}

try {
  applyEndpointResource(resource);
} catch (ResourceInvalidException e) {
  logger.error("EDS resource missing address fields: " + e.getMessage());
  skipAndNackResource(resource);
}

When it happens

Trigger: xDS response (EDS ClusterLoadAssignment endpoint or cluster address) where SocketAddress.address is the empty string — validateAddress is called from parse before attempting IP parsing.

Common situations: Control plane generating endpoints without setting the address field (proto default when field omitted); templated/generated config where a variable failed to substitute; hand-written EDS JSON/YAML missing 'address'.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — 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: Invalid IP add
• Failed to parse envoy.config.core.v3.Address: Port value %d
• Not implemented
• unsupported ExtAuthz service type: only grpc_service is supp
• Audience URL is empty. Metadata value must contain a valid U

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