grpc/grpc-java · error · ResourceInvalidException

Invalid ring hash function: " + ringHash.getHashFunction()

Error message

Invalid ring hash function: " + ringHash.getHashFunction()

What it means

gRPC-xDS only supports the XX_HASH hash function for the ring_hash load balancing policy. When an xDS Cluster's ring_hash config from the control plane specifies any other hash function, convertRingHashConfig rejects it because the hash function is not carried through to the returned service config for later validation, so it must fail fast here.

Source

Thrown at xds/src/main/java/io/grpc/xds/LoadBalancerConfigFactory.java:280

        } else {
          return serviceConfig;
        }
      }

      // If we could not find a Policy that we could both convert as well as find a provider for
      // then we have an invalid LB policy configuration.
      throw new ResourceInvalidException("Invalid LoadBalancingPolicy: " + loadBalancingPolicy);
    }

    /**
     * Converts a ring_hash {@link Any} configuration to service config format.
     */
    private static ImmutableMap<String, ?> convertRingHashConfig(RingHash ringHash)
        throws ResourceInvalidException {
      // The hash function needs to be validated here as it is not exposed in the returned
      // configuration for later validation.
      if (RingHash.HashFunction.XX_HASH != ringHash.getHashFunction()) {
        throw new ResourceInvalidException(
            "Invalid ring hash function: " + ringHash.getHashFunction());
      }

      return buildRingHashConfig(
          ringHash.hasMinimumRingSize() ? ringHash.getMinimumRingSize().getValue() : null,
          ringHash.hasMaximumRingSize() ? ringHash.getMaximumRingSize().getValue() : null);
    }

    private static ImmutableMap<String, ?> convertWeightedRoundRobinConfig(
        ClientSideWeightedRoundRobin wrr) throws ResourceInvalidException {
      try {
        return buildWrrConfig(
            wrr.hasBlackoutPeriod() ? Durations.toString(wrr.getBlackoutPeriod()) : null,
            wrr.hasWeightExpirationPeriod()
                ? Durations.toString(wrr.getWeightExpirationPeriod()) : null,
            wrr.hasOobReportingPeriod() ? Durations.toString(wrr.getOobReportingPeriod()) : null,
            wrr.hasEnableOobLoadReport() ? wrr.getEnableOobLoadReport().getValue() : null,
            wrr.hasWeightUpdatePeriod() ? Durations.toString(wrr.getWeightUpdatePeriod()) : null,

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Change the hash function in the Cluster's ring_hash config on the xDS management server to XX_HASH
2. Remove the hash_function field only if your control plane defaults to XX_HASH and confirm what is actually sent
3. Inspect the raw CDS response (e.g. grpc xDS debug logs / Envoy admin dump) to see which hash function is being sent
4. Check for stale control-plane versions that predate xx_hash support and upgrade them

Example fix

# before (Envoy/CDS cluster config)
ring_hash_lb_config:
  hash_function: MURMUR_HASH_2
# after
ring_hash_lb_config:
  hash_function: XX_HASH

// On the control plane / config source, before emitting the cluster:
if (!ringHashLbConfig.hasHashFunction()
    || ringHashLbConfig.getHashFunction() != RingHash.HashFunction.XX_HASH) {
  throw new IllegalArgumentException("ring_hash hash_function must be XX_HASH");
}

try {
  serviceConfig = convertToServiceConfig(cluster, ...);
} catch (ResourceInvalidException e) {
  logger.log(Level.SEVERE, "Rejecting xDS cluster: " + e.getMessage(), e);
  // fall back to a locally-configured LB policy or fail the resource
}

When it happens

Trigger: An LDS/CDS response delivers a Cluster with a RingHash lb_config whose hash_function field is set to something other than XX_HASH (e.g. MURMUR_HASH_2 or unset default), and the client converts the cluster into a service config via LoadBalancerConfigFactory.convertToServiceConfig.

Common situations: Control plane (Istio/Traffic Director/custom xDS server) emitting a legacy or non-default hash function; hand-written bootstrap/ADS fixtures copying examples that use murmur2; Envoy configs ported without updating the hash function to xx_hash.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cluster " + cluster.getName() + ": invalid ring hash functio
• Missing RingHash configuration
• Failed to parse lb config for cluster '" + cluster.getName()
• unsupported ExtAuthz service type: only grpc_service is supp
• Invalid duration in weighted round robin config: " + ex.getM

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