thanos-io/thanos · error

hashmod algorithm does not support shuffle sharding. Either…

Error message

hashmod algorithm does not support shuffle sharding. Either use Ketama or remove shuffle sharding configuration

What it means

newHashringConfig (hashmod branch) rejects a configuration that combines the hashmod algorithm with shuffle sharding (shardSize > 0). Shuffle sharding is only implemented for the Ketama algorithm, so the combination is unsupported and construction fails immediately.

Solutions

1. Either remove the shuffleSharding.shardSize (set to 0/omit) from the hashring config
2. Or change the algorithm to Ketama, which supports shuffle sharding
3. Restart/redeploy receivers so all nodes load the corrected hashring config

Example fix

// before
hashring: ring-0
algorithm: hashmod
shuffleSharding:
  shardSize: 3
// after (option A)
hashring: ring-0
algorithm: hashmod
// or option B
algorithm: ketama

func validateHashringCfg(cfg HashringConfig) error {
    if !strings.EqualFold(cfg.Algorithm, "ketama") && cfg.ShuffleSharding.ShardSize > 0 {
        return errors.New("shuffle sharding requires ketama algorithm")
    }
    return nil
}

ring, err := newHashringConfig(...)
if err != nil {
    return nil, fmt.Errorf("invalid hashring config: %w", err)
}

When it happens

Trigger: Hashring config sets algorithm: hashmod together with shuffleSharding.shardSize > 0 when the hashring config is parsed/built.

Common situations: Operator switches algorithm back to hashmod after previously using shuffle sharding but forgets to remove the shardSize; copied config templates that include shardSize by default.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• shard size is larger than number of nodes in hashring ( )
• configuration file is not parsable
• configuration file is empty
• endpoint address must be set
• failed to read configuration file

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

Appendix: source

Thrown at pkg/receive/hashring.go:738

		}
		m.tenantSets = append(m.tenantSets, t)
	}
	slices.SortFunc(m.nodes, func(a, b Endpoint) int {
		return strings.Compare(a.Address, b.Address)
	})
	return m, nil
}

func newHashring(algorithm HashringAlgorithm, endpoints []Endpoint, replicationFactor uint64, hashring string, tenants []string, shuffleShardingConfig ShuffleShardingConfig, reg prometheus.Registerer) (Hashring, error) {

	switch algorithm {
	case AlgorithmHashmod:
		ringImpl, err := newSimpleHashring(endpoints)
		if err != nil {
			return nil, err
		}
		if shuffleShardingConfig.ShardSize > 0 {
			return nil, fmt.Errorf("hashmod algorithm does not support shuffle sharding. Either use Ketama or remove shuffle sharding configuration")
		}
		return ringImpl, nil
	case AlgorithmKetama:
		ringImpl, err := newKetamaHashring(endpoints, SectionsPerNode, replicationFactor)
		if err != nil {
			return nil, err
		}
		if shuffleShardingConfig.ShardSize > 0 {
			if shuffleShardingConfig.ShardSize > len(endpoints) {
				return nil, fmt.Errorf("shard size %d is larger than number of nodes in hashring %s (%d)", shuffleShardingConfig.ShardSize, hashring, len(endpoints))
			}
			return newShuffleShardHashring(ringImpl, shuffleShardingConfig, replicationFactor, reg, hashring)
		}
		return ringImpl, nil
	default:
		l := log.NewNopLogger()
		level.Warn(l).Log("msg", "Unrecognizable hashring algorithm. Fall back to hashmod algorithm.",
			"hashring", hashring,

View on GitHub (pinned to 35b8b99117)