{"record":{"id":"5698853263f5f7a3","repo":"thanos-io/thanos","slug":"hashmod-algorithm-does-not-support-az-aware-hashri","errorCode":null,"errorMessage":"Hashmod algorithm does not support AZ aware hashring configuration. Either use Ketama or remove AZ configuration.","messagePattern":"Hashmod algorithm does not support AZ aware hashring configuration\\. Either use Ketama or remove AZ configuration\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/receive/hashring.go","lineNumber":98,"sourceCode":"func (s SingleNodeHashring) GetN(_ string, _ *prompb.TimeSeries, n uint64) (Endpoint, error) {\n\tif n > 0 {\n\t\treturn Endpoint{}, &insufficientNodesError{have: 1, want: n + 1}\n\t}\n\treturn Endpoint{\n\t\tAddress:          string(s),\n\t\tCapNProtoAddress: string(s),\n\t}, nil\n}\n\n// simpleHashring represents a group of nodes handling write requests by hashmoding individual series.\ntype simpleHashring []Endpoint\n\nfunc (s simpleHashring) Close() {}\n\nfunc newSimpleHashring(endpoints []Endpoint) (Hashring, error) {\n\tfor i := range endpoints {\n\t\tif endpoints[i].AZ != \"\" {\n\t\t\treturn nil, errors.New(\"Hashmod algorithm does not support AZ aware hashring configuration. Either use Ketama or remove AZ configuration.\")\n\t\t}\n\t}\n\tslices.SortFunc(endpoints, func(a, b Endpoint) int {\n\t\treturn strings.Compare(a.Address, b.Address)\n\t})\n\n\treturn simpleHashring(endpoints), nil\n}\n\nfunc (s simpleHashring) Nodes() []Endpoint {\n\treturn s\n}\n\n// Get returns a target to handle the given tenant and time series.\nfunc (s simpleHashring) Get(tenant string, ts *prompb.TimeSeries) (Endpoint, error) {\n\treturn s.GetN(tenant, ts, 0)\n}\n","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/receive/hashring.go#L80-L116","documentation":"newSimpleHashring refuses to build a hashmod-based hashring when any configured endpoint carries a non-empty AZ (availability zone) field. Hashmod hashing cannot be AZ-aware, so mixing hashmod with AZ configuration is treated as a configuration error rather than silently ignored.","triggerScenarios":"Constructing a hashring with algorithm 'hashmod' (default) while one or more endpoints in the hashring file/config set 'az' to a value, e.g. {\"endpoints\":[{\"address\":\"...\",\"az\":\"zone-a\"}]}.","commonSituations":"Operators copying an AZ example config from Ketama docs into a hashmod setup; partial migration where some endpoints gained az fields; tooling that always emits az keys.","solutions":["Switch the hashring algorithm to 'ketama' in the hashring configuration.","Or remove the az field from all endpoints, keeping hashmod.","Regenerate/reload the hashring config on all receive nodes after the change.","Note ketama requires endpoints count >= replication factor; plan accordingly."],"exampleFix":"// before\n{\"endpoints\":[{\"address\":\"127.0.0.1:10901\",\"az\":\"zone-a\"}]}\n// after\n{\"endpoints\":[{\"address\":\"127.0.0.1:10901\"}]}\n// or use ketama\n{\"algorithm\":\"ketama\",\"endpoints\":[{\"address\":\"127.0.0.1:10901\",\"az\":\"zone-a\"}]}","handlingStrategy":"validation","validationCode":"func validateHashring(cfg HashringConfig) error {\n  if (cfg.Algorithm == \"\" || cfg.Algorithm == \"hashmod\") {\n    for _, ep := range cfg.Endpoints { if ep.AZ != \"\" { return fmt.Errorf(\"az set on hashmod endpoint %s\", ep.Address) } }\n  }\n  return nil\n}","typeGuard":"func azCompatible(cfg HashringConfig) bool { return cfg.Algorithm == \"ketama\" || !hasAnyAZ(cfg.Endpoints) }","tryCatchPattern":"h, err := newHashring(cfg); if err != nil { return fmt.Errorf(\"hashring init: %w\", err) }","preventionTips":["Validate hashring files in CI before rollout","Use one algorithm consistently across all receive nodes","Document that az fields require ketama"],"tags":["thanos","configuration","hashring"],"backgroundTag":"incompatible-source-type","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"}