Hashmod algorithm does not support AZ aware hashring…

Error message

Hashmod algorithm does not support AZ aware hashring configuration. Either use Ketama or remove AZ configuration.

What it means

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.

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.

Example fix

// before
{"endpoints":[{"address":"127.0.0.1:10901","az":"zone-a"}]}
// after
{"endpoints":[{"address":"127.0.0.1:10901"}]}
// or use ketama
{"algorithm":"ketama","endpoints":[{"address":"127.0.0.1:10901","az":"zone-a"}]}

Defensive patterns

Strategy: validation

Validate before calling

func validateHashring(cfg HashringConfig) error {
  if (cfg.Algorithm == "" || cfg.Algorithm == "hashmod") {
    for _, ep := range cfg.Endpoints { if ep.AZ != "" { return fmt.Errorf("az set on hashmod endpoint %s", ep.Address) } }
  }
  return nil
}

Type guard

func azCompatible(cfg HashringConfig) bool { return cfg.Algorithm == "ketama" || !hasAnyAZ(cfg.Endpoints) }

Try / catch

h, err := newHashring(cfg); if err != nil { return fmt.Errorf("hashring init: %w", err) }

Prevention

Validate hashring files in CI before rollout
Use one algorithm consistently across all receive nodes
Document that az fields require ketama

When it happens

Trigger: 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"}]}.

Common situations: 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.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/5698853263f5f7a3. Report an issue: GitHub.

Appendix: source

Thrown at pkg/receive/hashring.go:98

func (s SingleNodeHashring) GetN(_ string, _ *prompb.TimeSeries, n uint64) (Endpoint, error) {
	if n > 0 {
		return Endpoint{}, &insufficientNodesError{have: 1, want: n + 1}
	}
	return Endpoint{
		Address:          string(s),
		CapNProtoAddress: string(s),
	}, nil
}

// simpleHashring represents a group of nodes handling write requests by hashmoding individual series.
type simpleHashring []Endpoint

func (s simpleHashring) Close() {}

func newSimpleHashring(endpoints []Endpoint) (Hashring, error) {
	for i := range endpoints {
		if endpoints[i].AZ != "" {
			return nil, errors.New("Hashmod algorithm does not support AZ aware hashring configuration. Either use Ketama or remove AZ configuration.")
		}
	}
	slices.SortFunc(endpoints, func(a, b Endpoint) int {
		return strings.Compare(a.Address, b.Address)
	})

	return simpleHashring(endpoints), nil
}

func (s simpleHashring) Nodes() []Endpoint {
	return s
}

// Get returns a target to handle the given tenant and time series.
func (s simpleHashring) Get(tenant string, ts *prompb.TimeSeries) (Endpoint, error) {
	return s.GetN(tenant, ts, 0)
}

View on GitHub (pinned to 35b8b99117)