thanos-io/thanos · error

unknown replication protocol

Error message

unknown replication protocol %v

What it means

This error is a programmer/configuration invariant error raised in peerGroup.getConnection when p.replicationProtocol is neither CapNProtoReplication nor ProtobufReplication. The replication protocol field is set from flags/config at peerGroup construction, so hitting this default branch means an unsupported or unset protocol value reached the switch. It is not transient — every dial attempt for a non-local endpoint will fail with the same message.

Solutions

1. Check which replication protocol flag/version produced this value and upgrade/downgrade the affected Thanos component so both sides agree.
2. Inspect the code constructing peerGroup and ensure replicationProtocol is explicitly set to CapNProtoReplication or ProtobufReplication.
3. If setting the protocol from config, validate it against the supported enum before constructing the peerGroup.
4. Report a bug if a stock Thanos binary hits this, since valid flags should always map to a supported protocol.

Example fix

// before: protocol parsed unvalidated
p.replicationProtocol = ReplicationProtocol(cfg["protocol"])
// after: validate against supported values
proto, err := parseReplicationProtocol(cfg["protocol"])
if err != nil {
	return nil, errors.Wrap(err, "unsupported replication protocol in config")
}
p.replicationProtocol = proto

// Go: validate protocol enum before building peerGroup
switch proto {
case CapNProtoReplication, ProtobufReplication:
	// ok
default:
	return nil, errors.Errorf("unsupported replication protocol %v", proto)
}

When it happens

Trigger: Returned whenever getConnection reaches the switch on p.replicationProtocol with an unrecognized value, i.e. a nil/zero or out-of-enum ReplicationProtocol value was used when building the peerGroup.

Common situations: Newer/older Thanos binaries or clients speaking a protocol the peer doesn't support; a code path constructing peerGroup without setting replicationProtocol; custom integrations setting the protocol via an unvalidated config value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• raw resolution must be higher than the minimum block size…
• 5m resolution retention must be higher than the minimum…
• building gRPC client
• preparing command failed
• error while parsing config for request logging

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

Appendix: source

Thrown at pkg/receive/handler.go:1986

	if isLocalEndpoint(endpoint, p.localEndpoint) {
		client = &localAsyncWriter{
			w: p.writer,
		}
	} else {
		switch p.replicationProtocol {
		case CapNProtoReplication:
			client = writecapnp.NewRemoteWriteClient(writecapnp.NewTCPDialer(endpoint.CapNProtoAddress), p.logger)

		case ProtobufReplication:
			conn, err := p.dialer(endpoint.Address, p.dialOpts...)
			if err != nil {
				p.markPeerUnavailableUnlocked(endpoint)
				dialError := errors.Wrap(err, "failed to dial peer")
				return nil, errors.Wrap(dialError, errUnavailable.Error())
			}
			client = newProtobufPeer(conn)
		default:
			return nil, errors.Errorf("unknown replication protocol %v", p.replicationProtocol)
		}
	}

	var delay time.Duration
	if p.conns.Load() == 2 {
		delay = p.maxArtificialDelay
	}

	p.connections[endpoint] = newPeerWorker(client, p.forwardDelay.WithLabelValues(endpoint.Address), p.asyncForwardWorkersCount, delay)
	return p.connections[endpoint], nil
}

func (p *peerGroup) markPeerUnavailable(addr Endpoint) {
	p.m.Lock()
	defer p.m.Unlock()

	p.markPeerUnavailableUnlocked(addr)
}

View on GitHub (pinned to 35b8b99117)