{"record":{"id":"7083215ce95d74a9","repo":"grpc/grpc-java","slug":"invalid-ring-hash-function-ringhash-gethashfu","errorCode":null,"errorMessage":"Invalid ring hash function: \" + ringHash.getHashFunction()","messagePattern":"Invalid ring hash function: \" \\+ ringHash\\.getHashFunction\\(\\)","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/LoadBalancerConfigFactory.java","lineNumber":280,"sourceCode":"        } else {\n          return serviceConfig;\n        }\n      }\n\n      // If we could not find a Policy that we could both convert as well as find a provider for\n      // then we have an invalid LB policy configuration.\n      throw new ResourceInvalidException(\"Invalid LoadBalancingPolicy: \" + loadBalancingPolicy);\n    }\n\n    /**\n     * Converts a ring_hash {@link Any} configuration to service config format.\n     */\n    private static ImmutableMap<String, ?> convertRingHashConfig(RingHash ringHash)\n        throws ResourceInvalidException {\n      // The hash function needs to be validated here as it is not exposed in the returned\n      // configuration for later validation.\n      if (RingHash.HashFunction.XX_HASH != ringHash.getHashFunction()) {\n        throw new ResourceInvalidException(\n            \"Invalid ring hash function: \" + ringHash.getHashFunction());\n      }\n\n      return buildRingHashConfig(\n          ringHash.hasMinimumRingSize() ? ringHash.getMinimumRingSize().getValue() : null,\n          ringHash.hasMaximumRingSize() ? ringHash.getMaximumRingSize().getValue() : null);\n    }\n\n    private static ImmutableMap<String, ?> convertWeightedRoundRobinConfig(\n        ClientSideWeightedRoundRobin wrr) throws ResourceInvalidException {\n      try {\n        return buildWrrConfig(\n            wrr.hasBlackoutPeriod() ? Durations.toString(wrr.getBlackoutPeriod()) : null,\n            wrr.hasWeightExpirationPeriod()\n                ? Durations.toString(wrr.getWeightExpirationPeriod()) : null,\n            wrr.hasOobReportingPeriod() ? Durations.toString(wrr.getOobReportingPeriod()) : null,\n            wrr.hasEnableOobLoadReport() ? wrr.getEnableOobLoadReport().getValue() : null,\n            wrr.hasWeightUpdatePeriod() ? Durations.toString(wrr.getWeightUpdatePeriod()) : null,","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/LoadBalancerConfigFactory.java#L262-L298","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Change the hash function in the Cluster's ring_hash config on the xDS management server to XX_HASH","Remove the hash_function field only if your control plane defaults to XX_HASH and confirm what is actually sent","Inspect the raw CDS response (e.g. grpc xDS debug logs / Envoy admin dump) to see which hash function is being sent","Check for stale control-plane versions that predate xx_hash support and upgrade them"],"exampleFix":"# before (Envoy/CDS cluster config)\nring_hash_lb_config:\n  hash_function: MURMUR_HASH_2\n# after\nring_hash_lb_config:\n  hash_function: XX_HASH","handlingStrategy":"validation","validationCode":"// On the control plane / config source, before emitting the cluster:\nif (!ringHashLbConfig.hasHashFunction()\n    || ringHashLbConfig.getHashFunction() != RingHash.HashFunction.XX_HASH) {\n  throw new IllegalArgumentException(\"ring_hash hash_function must be XX_HASH\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  serviceConfig = convertToServiceConfig(cluster, ...);\n} catch (ResourceInvalidException e) {\n  logger.log(Level.SEVERE, \"Rejecting xDS cluster: \" + e.getMessage(), e);\n  // fall back to a locally-configured LB policy or fail the resource\n}","preventionTips":["Always set hash_function: XX_HASH in ring_hash configs","Validate CDS payloads with Envoy config dump before rollout","Keep control plane and grpc-xds versions aligned"],"tags":["grpc","xds","load-balancing","ring-hash","config-validation"],"backgroundTag":"invalid-enum-value","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"}