netbirdio/netbird · error

unrecognized SyncMessageVersion

Error message

unrecognized SyncMessageVersion

What it means

ValidateSyncMessageVersion rejects a requested sync-protocol version outside the range [0, HighestSyncMessageVersion] (currently ComponentNetworkMap = 1). The sync layer negotiates a message version at login; this error, wrapped in 'sync message version must between 0 and N', means the caller asked for a version this build does not implement. A nil pointer means 'support all' and always passes.

Source

Thrown at shared/management/grpc/sync_message_versions.go:18

package grpc

import (
	"errors"
	"fmt"
)

type SyncMessageVersion uint16

const (
	Base SyncMessageVersion = iota
	ComponentNetworkMap
)

const DefaultSyncMessageVersion = Base
const HighestSyncMessageVersion = ComponentNetworkMap

var ErrorUnrecognizedSyncMessageVersion = errors.New("unrecognized SyncMessageVersion")

func ValidateSyncMessageVersion(v *int) error {
	// empty list == we support all available versions
	if v == nil {
		return nil
	}
	if *v < 0 || *v > int(HighestSyncMessageVersion) {
		return fmt.Errorf("sync message version must between 0 and %d, %w", HighestSyncMessageVersion, ErrorUnrecognizedSyncMessageVersion)
	}
	return nil
}

// returns SyncMessage version from config, or highest available version if the config is missing or
// base if it is invalid
// the assumption is ValidateSyncMessageVersion() has been called before using SyncMessageVersionFromConfig()
func SyncMessageVersionFromConfig(v *int) SyncMessageVersion {
	if v == nil {
		return DefaultSyncMessageVersion

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Leave the version nil (or Base) to use the default negotiation
2. Clamp the requested value to HighestSyncMessageVersion before validating
3. Upgrade the component that expects the newer sync version

Example fix

// before
v := 5
err := grpc.ValidateSyncMessageVersion(&v)

// after
v := int(grpc.HighestSyncMessageVersion)
err := grpc.ValidateSyncMessageVersion(&v)

v := requestedVersion
if v > int(grpc.HighestSyncMessageVersion) {
	v = int(grpc.HighestSyncMessageVersion)
}
if err := grpc.ValidateSyncMessageVersion(&v); err != nil {
	return err
}

func isValidSyncVersion(v int) bool {
	return v >= 0 && v <= int(grpc.HighestSyncMessageVersion)
}

if err := grpc.ValidateSyncMessageVersion(&v); err != nil {
	if errors.Is(err, grpc.ErrorUnrecognizedSyncMessageVersion) {
		// fall back to the default version and retry
	}
	return err
}

When it happens

Trigger: Passing an int above HighestSyncMessageVersion or a negative value, e.g. a hand-built login flow with SyncMessageVersion taken from config or copied from a newer agent.

Common situations: Downgraded agent/management using config from a newer version; custom integrations pinning a sync version; experimental builds referencing not-yet-shipped versions.

Related errors

• failed to create auth client: %v
• expose service: %v
• failed to create auth client: %v
• getting pkce authorization flow info failed with error: %v
• no SSO provider returned from management. Please proceed wit

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/7ae4ad54c2d7125c. Report an issue: GitHub.