{"record":{"id":"e38ec7ea0cd98cec","repo":"grpc/grpc-java","slug":"cluster-cluster-getname-invalid-ring-ha","errorCode":null,"errorMessage":"Cluster \" + cluster.getName() + \": invalid ring hash function: \" + lbConfig","messagePattern":"Cluster \" \\+ cluster\\.getName\\(\\) \\+ \": invalid ring hash function: \" \\+ lbConfig","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/LoadBalancerConfigFactory.java","lineNumber":437,"sourceCode":"          break;\n        default:\n      }\n      throw new ResourceInvalidException(\n          \"Cluster \" + cluster.getName() + \": unsupported lb policy: \" + cluster.getLbPolicy());\n    }\n\n    /**\n     * Creates a new ring_hash service config JSON object based on the old {@link RingHashLbConfig}\n     * config message.\n     */\n    private static ImmutableMap<String, ?> convertRingHashConfig(Cluster cluster)\n        throws ResourceInvalidException {\n      RingHashLbConfig lbConfig = cluster.getRingHashLbConfig();\n\n      // The hash function needs to be validated here as it is not exposed in the returned\n      // configuration for later validation.\n      if (lbConfig.getHashFunction() != RingHashLbConfig.HashFunction.XX_HASH) {\n        throw new ResourceInvalidException(\n            \"Cluster \" + cluster.getName() + \": invalid ring hash function: \" + lbConfig);\n      }\n\n      return buildRingHashConfig(\n          lbConfig.hasMinimumRingSize() ? (Long) lbConfig.getMinimumRingSize().getValue() : null,\n          lbConfig.hasMaximumRingSize() ? (Long) lbConfig.getMaximumRingSize().getValue() : null);\n    }\n\n    /**\n     * Creates a new least_request service config JSON object based on the old {@link\n     * LeastRequestLbConfig} config message.\n     */\n    private static ImmutableMap<String, ?> convertLeastRequestConfig(Cluster cluster) {\n      LeastRequestLbConfig lbConfig = cluster.getLeastRequestLbConfig();\n      return buildLeastRequestConfig(\n          lbConfig.hasChoiceCount() ? (Integer) lbConfig.getChoiceCount().getValue() : null);\n    }\n  }","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/LoadBalancerConfigFactory.java#L419-L455","documentation":"The legacy RingHashLbConfig on a Cluster must use the XX_HASH hash function. convertRingHashConfig validates this before building the ring_hash service config because the hash function is not represented in the returned JSON config, so an invalid value would otherwise be silently ignored.","triggerScenarios":"convertToServiceConfig dispatches a Cluster with lb_policy RING_HASH to convertRingHashConfig; the Cluster's RingHashLbConfig.hash_function is anything other than XX_HASH.","commonSituations":"Older Envoy/Istio configs defaulting to murmur2; control plane templates not migrated after xx_hash became required; hand-rolled xDS test servers emitting deprecated hash functions.","solutions":["Change the ring hash lb config's hash_function to XX_HASH on the management server","If hash_function is omitted, ensure the control plane's default is XX_HASH or set it explicitly","Inspect the CDS payload (xDS debug logging) to confirm what is being sent","Upgrade control plane images that predate xx_hash defaulting"],"exampleFix":"// before\nRingHashLbConfig.newBuilder().setHashFunction(HashFunction.MURMUR_HASH_2)\n// after\nRingHashLbConfig.newBuilder().setHashFunction(HashFunction.XX_HASH)","handlingStrategy":"validation","validationCode":"if (lbConfig.getHashFunction() != RingHashLbConfig.HashFunction.XX_HASH) {\n  throw new IllegalArgumentException(\"ring hash must use XX_HASH, got \" + lbConfig.getHashFunction());\n}","typeGuard":null,"tryCatchPattern":"try {\n  serviceConfig = convertRingHashConfig(cluster);\n} catch (ResourceInvalidException e) {\n  logger.warning(\"ring_hash config rejected: \" + e.getMessage());\n  // fail resource or substitute a compliant ring_hash config\n}","preventionTips":["Migrate all ring_hash configs to XX_HASH","Make XX_HASH the explicit value, not an implicit default","Diff control-plane templates against Envoy's current defaults"],"tags":["grpc","xds","ring-hash","load-balancing","enum-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"}