{"record":{"id":"33e85d5e19cf5d71","repo":"thanos-io/thanos","slug":"request-replica-exceeds-receiver-replication-facto","errorCode":null,"errorMessage":"request replica exceeds receiver replication factor","messagePattern":"request replica exceeds receiver replication factor","errorType":"error_code","errorClass":null,"httpStatus":400,"severity":"error","filePath":"pkg/receive/handler.go","lineNumber":91,"sourceCode":"\t// LimitStatsQueryParam is the query parameter for limiting the amount of returned TSDB stats.\n\tLimitStatsQueryParam = \"limit\"\n\t// Labels for metrics.\n\tlabelSuccess = \"success\"\n\tlabelError   = \"error\"\n)\n\ntype ReplicationProtocol string\n\nconst (\n\tProtobufReplication  ReplicationProtocol = \"protobuf\"\n\tCapNProtoReplication ReplicationProtocol = \"capnproto\"\n)\n\nvar (\n\t// errConflict is returned whenever an operation fails due to any conflict-type error.\n\terrConflict = errors.New(\"conflict\")\n\n\terrBadReplica  = errors.New(\"request replica exceeds receiver replication factor\")\n\terrNotReady    = errors.New(\"target not ready\")\n\terrUnavailable = errors.New(\"target not available\")\n\n\terrValidation = errors.New(\"validation error\")\n)\n\ntype WriteableStoreAsyncClient interface {\n\tstorepb.WriteableStoreClient\n\tRemoteWriteAsync(context.Context, *storepb.WriteRequest, endpointReplica, []int, chan writeResponse, func(error))\n\t// TryRemoteWriteAsync submits the request without blocking. Returns false if the peer's\n\t// worker pool is at capacity; the caller should fall back to RemoteWriteAsync.\n\tTryRemoteWriteAsync(context.Context, *storepb.WriteRequest, endpointReplica, []int, chan writeResponse, func(error)) bool\n}\n\n// Options for the web Handler.\ntype Options struct {\n\tWriter                  *Writer\n\tListenAddress           string","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/receive/handler.go#L73-L109","documentation":"errBadReplica is the sentinel returned by Write and receiveOTLPHTTP when an incoming request's replication factor exceeds the receiver's configured replication factor. The handler maps it to http.StatusBadRequest (400) and capnp maps it to WriteError_invalidArgument. It signals a configuration mismatch between sending and receiving Thanos receive nodes.","triggerScenarios":"A write request arrives (via Write or receiveOTLPHTTP) whose embedded replication factor (from the sender's --receive.replication-factor) is greater than the local receiver's replication factor, so the receiver cannot honor it.","commonSituations":"Rolling update where some replicas run a higher --receive.replication-factor than others, hashring rebalancing with mixed configuration, a client configured against a different cluster's settings.","solutions":["Align --receive.replication-factor to the same value on all receiver nodes in the cluster","Check the sending node's configuration vs the receiving node's during a rolling deploy","If lowering the factor intentionally, update the hashring and redeploy the whole cluster consistently","Inspect the wrapped error at the write path to confirm which side reports the mismatch"],"exampleFix":"// before: sender\n--receive.replication-factor=5\n// after (matched with receivers)\n--receive.replication-factor=3","handlingStrategy":"validation","validationCode":"if reqReplicationFactor > r.replicationFactor {\n    return fmt.Errorf(\"request replication factor %d exceeds receiver's %d\", reqReplicationFactor, r.replicationFactor)\n}","typeGuard":"func isBadReplica(err error) bool {\n    return errors.Is(errors.Cause(err), errBadReplica)\n}","tryCatchPattern":"err := r.Write(ctx, req)\nif err != nil && errors.Is(errors.Cause(err), errBadReplica) {\n    // do not retry: fix replication-factor configuration first\n    return http.StatusBadRequest\n}","preventionTips":["Keep --receive.replication-factor identical on every receiver in the cluster","Add a config-drift check in deployment tooling across receiver replicas","During rolling updates, deploy receivers before senders when lowering the factor","Document the cluster-wide factor so new nodes inherit the correct value"],"tags":["replication","configuration","mismatch"],"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"}