shard size is larger than number of nodes in hashring ( )

Error message

shard size %d is larger than number of nodes in hashring %s (%d)

What it means

In the Ketama branch of newHashringConfig, when shuffle sharding is enabled the configured ShardSize must not exceed the total number of endpoints in the hashring. If it does, construction fails because a tenant shard cannot contain more nodes than exist, and the error names the hashring and its node count.

Solutions

Set shuffleSharding.shardSize to a value <= the number of endpoints in the hashring
Scale the receiver deployment so the hashring has at least shardSize endpoints
Verify endpoint discovery lists all expected receivers (check the parsed endpoints count)

Example fix

// before
algorithm: ketama
shuffleSharding:
  shardSize: 8   # hashring only has 3 endpoints
// after
shuffleSharding:
  shardSize: 3

Defensive patterns

Strategy: validation

Validate before calling

func shardFitsRing(shardSize, numEndpoints int) bool {
    return shardSize <= 0 || shardSize <= numEndpoints
}
if !shardFitsRing(cfg.ShardSize, len(endpoints)) {
    return errors.New("shard size exceeds hashring endpoints")
}

Try / catch

ring, err := newHashringConfig(...)
if err != nil {
    log.Error("hashring build failed; check shardSize vs endpoint count", "err", err)
    return err
}

Prevention

Recompute shardSize after any scale-down of receivers
Keep shardSize well below total node count for headroom
Verify discovered endpoint count before building the ring

When it happens

Trigger: hashring config with algorithm: ketama, shuffleSharding.shardSize = N where N > len(endpoints) of that hashring; hit when building the hashring config (e.g. on startup or config reload).

Common situations: Endpoints removed/scaled down but shardSize left at its old larger value; copy-pasted shardSize from a bigger cluster; typo in shardSize (e.g. 30 instead of 3).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at pkg/receive/hashring.go:748

	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,
			"tenants", tenants)
		if shuffleShardingConfig.ShardSize > 0 {
			return nil, fmt.Errorf("hashmod algorithm does not support shuffle sharding. Either use Ketama or remove shuffle sharding configuration")
		}
		return newSimpleHashring(endpoints)
	}
}

View on GitHub (pinned to 35b8b99117)