{"record":{"id":"cae5061f6d478af8","repo":"thanos-io/thanos","slug":"shard-size-d-is-larger-than-number-of-nodes-in-ha","errorCode":null,"errorMessage":"shard size %d is larger than number of nodes in hashring %s (%d)","messagePattern":"shard size (.+?) is larger than number of nodes in hashring (.+?) \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/receive/hashring.go","lineNumber":748,"sourceCode":"\n\tswitch algorithm {\n\tcase AlgorithmHashmod:\n\t\tringImpl, err := newSimpleHashring(endpoints)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif shuffleShardingConfig.ShardSize > 0 {\n\t\t\treturn nil, fmt.Errorf(\"hashmod algorithm does not support shuffle sharding. Either use Ketama or remove shuffle sharding configuration\")\n\t\t}\n\t\treturn ringImpl, nil\n\tcase AlgorithmKetama:\n\t\tringImpl, err := newKetamaHashring(endpoints, SectionsPerNode, replicationFactor)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif shuffleShardingConfig.ShardSize > 0 {\n\t\t\tif shuffleShardingConfig.ShardSize > len(endpoints) {\n\t\t\t\treturn nil, fmt.Errorf(\"shard size %d is larger than number of nodes in hashring %s (%d)\", shuffleShardingConfig.ShardSize, hashring, len(endpoints))\n\t\t\t}\n\t\t\treturn newShuffleShardHashring(ringImpl, shuffleShardingConfig, replicationFactor, reg, hashring)\n\t\t}\n\t\treturn ringImpl, nil\n\tdefault:\n\t\tl := log.NewNopLogger()\n\t\tlevel.Warn(l).Log(\"msg\", \"Unrecognizable hashring algorithm. Fall back to hashmod algorithm.\",\n\t\t\t\"hashring\", hashring,\n\t\t\t\"tenants\", tenants)\n\t\tif shuffleShardingConfig.ShardSize > 0 {\n\t\t\treturn nil, fmt.Errorf(\"hashmod algorithm does not support shuffle sharding. Either use Ketama or remove shuffle sharding configuration\")\n\t\t}\n\t\treturn newSimpleHashring(endpoints)\n\t}\n}\n","sourceCodeStart":730,"sourceCodeEnd":764,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/receive/hashring.go#L730-L764","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","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)"],"exampleFix":"// before\nalgorithm: ketama\nshuffleSharding:\n  shardSize: 8   # hashring only has 3 endpoints\n// after\nshuffleSharding:\n  shardSize: 3","handlingStrategy":"validation","validationCode":"func shardFitsRing(shardSize, numEndpoints int) bool {\n    return shardSize <= 0 || shardSize <= numEndpoints\n}\nif !shardFitsRing(cfg.ShardSize, len(endpoints)) {\n    return errors.New(\"shard size exceeds hashring endpoints\")\n}","typeGuard":null,"tryCatchPattern":"ring, err := newHashringConfig(...)\nif err != nil {\n    log.Error(\"hashring build failed; check shardSize vs endpoint count\", \"err\", err)\n    return err\n}","preventionTips":["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"],"tags":["hashring","shuffle-sharding","capacity","config"],"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"}