grpc/grpc-java · error · ResourceInvalidException

Failed to parse envoy.config.core.v3.Address: Port value %d

Error message

Failed to parse envoy.config.core.v3.Address: Port value %d out of range 1-65535.

What it means

XdsEndpointResource.validateAddress checks that the SocketAddress port fits in the valid 1-65535 range. The port is stored in the proto as uint32, so values above 65535 are representable but invalid for TCP; the validator converts it to an unsigned long and throws ResourceInvalidException 'Port value N out of range 1-65535.', causing the xDS resource to be rejected.

Source

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

      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. Correct the port_value in the management server config to be within 1-65535.
2. Find and fix the producer of the bad value (look for byte-swap/endianness or wrong-field bugs in the control plane or config generation tooling).
3. Validate port ranges in your config-generation pipeline before publishing xDS resources.
4. Inspect the exact resource in ADS logs to confirm which endpoint carries the out-of-range port.

Example fix

# before
address: { socket_address: { address: "10.0.0.5", port_value: 987654 } }

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

int port = socketAddress.getPortValue();
if (Integer.toUnsignedLong(port) < 1 || Integer.toUnsignedLong(port) > 65535) {
  throw new IllegalArgumentException("port_value must be 1-65535, got: " + Integer.toUnsignedLong(port));
}

static boolean isPortInRange(long port) {
  return port >= 1 && port <= 65535;
}

try {
  applyEndpointResource(resource);
} catch (ResourceInvalidException e) {
  logger.error("xDS resource port out of range: " + e.getMessage());
  rejectAndNack(resource);
}

When it happens

Trigger: An xDS SocketAddress whose port_value (uint32) exceeds 65535 in an EDS/cluster address; validateAddress is invoked from XdsEndpointResource.parse after the address-string check passes.

Common situations: Control-plane or tooling bug writing large uint32 values (e.g. accidental byte-order swaps producing 0x… values, or passing an offset/hash instead of a port); generated configs where a placeholder was replaced by a non-port number.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

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

Related errors

• Header value length exceeds maximum allowed length
• Failed to parse envoy.config.core.v3.Address: Invalid IP add
• Failed to parse envoy.config.core.v3.Address: Address field
• Not implemented
• unsupported ExtAuthz service type: only grpc_service is supp

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