{"record":{"id":"9042c7ef07f01881","repo":"thanos-io/thanos","slug":"ketama-amount-of-endpoints-needs-to-be-larger-tha","errorCode":null,"errorMessage":"ketama: amount of endpoints needs to be larger than replication factor","messagePattern":"ketama: amount of endpoints needs to be larger than replication factor","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/receive/hashring.go","lineNumber":153,"sourceCode":"func (p sections) Len() int           { return len(p) }\nfunc (p sections) Less(i, j int) bool { return p[i].hash < p[j].hash }\nfunc (p sections) Swap(i, j int)      { p[i], p[j] = p[j], p[i] }\nfunc (p sections) Sort()              { sort.Sort(p) }\n\n// ketamaHashring represents a group of nodes handling write requests with consistent hashing.\ntype ketamaHashring struct {\n\tendpoints    []Endpoint\n\tsections     sections\n\tnumEndpoints uint64\n}\n\nfunc (s ketamaHashring) Close() {}\n\nfunc newKetamaHashring(endpoints []Endpoint, sectionsPerNode int, replicationFactor uint64) (*ketamaHashring, error) {\n\tnumSections := len(endpoints) * sectionsPerNode\n\n\tif len(endpoints) < int(replicationFactor) {\n\t\treturn nil, errors.New(\"ketama: amount of endpoints needs to be larger than replication factor\")\n\n\t}\n\thash := xxhash.New()\n\tavailabilityZones := make(map[string]struct{})\n\tringSections := make(sections, 0, numSections)\n\n\tfor endpointIndex, endpoint := range endpoints {\n\t\tavailabilityZones[endpoint.AZ] = struct{}{}\n\t\tfor i := 1; i <= sectionsPerNode; i++ {\n\t\t\t_, _ = hash.Write([]byte(endpoint.Address + \":\" + strconv.Itoa(i)))\n\t\t\tn := &section{\n\t\t\t\taz:            endpoint.AZ,\n\t\t\t\tendpointIndex: uint64(endpointIndex),\n\t\t\t\thash:          hash.Sum64(),\n\t\t\t\treplicas:      make([]uint64, 0, replicationFactor),\n\t\t\t}\n\n\t\t\tringSections = append(ringSections, n)","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/receive/hashring.go#L135-L171","documentation":"newKetamaHashring validates that the number of ring endpoints is at least the replication factor, since each series must be written to that many distinct nodes on the ring. With fewer endpoints than the replication factor, AZ-aware or replicated assignment is impossible, so construction fails with this error.","triggerScenarios":"Building a ketama hashring where len(endpoints) < replicationFactor, e.g. 1 endpoint with replicationFactor 3, typically via getTenantShard/newHashring from the hashring config.","commonSituations":"Testing with a single receive node while replication factor is still 3; sharding a tenant to a small subset of endpoints smaller than the global replication factor; partially failed config rollout leaving fewer endpoints.","solutions":["Add more endpoints to the hashring so the count is >= replication factor.","Lower the replication factor in the receive configuration to be <= number of endpoints.","Fix tenant shard config (Shard/Hashring splits) so each shard retains at least replicationFactor endpoints.","Verify the hashring file deployed to all nodes lists all running receive nodes."],"exampleFix":"# before: 1 endpoint, replicationFactor 3\nreplicationFactor: 3\nendpoints:\n  - address: 127.0.0.1:10901\n# after: add endpoints\nendpoints:\n  - address: 127.0.0.1:10901\n  - address: 127.0.0.2:10901\n  - address: 127.0.0.3:10901","handlingStrategy":"validation","validationCode":"func validateKetama(cfg HashringConfig, rf uint64) error {\n  if uint64(len(cfg.Endpoints)) < rf {\n    return fmt.Errorf(\"need >= %d endpoints, have %d\", rf, len(cfg.Endpoints))\n  }\n  return nil\n}","typeGuard":"func ketamaViable(n int, rf uint64) bool { return uint64(n) >= rf }","tryCatchPattern":"hr, err := newKetamaHashring(eps, sections, rf); if err != nil { return nil, fmt.Errorf(\"ketama init: %w\", err) }","preventionTips":["Assert endpoint count >= replication factor in config tests","When sharding tenants, ensure each shard keeps enough endpoints","Lower replication factor for small/test clusters"],"tags":["thanos","configuration","hashring","replication"],"backgroundTag":"invalid-config-value","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}