{"record":{"id":"7ae4ad54c2d7125c","repo":"netbirdio/netbird","slug":"unrecognized-syncmessageversion","errorCode":null,"errorMessage":"unrecognized SyncMessageVersion","messagePattern":"unrecognized SyncMessageVersion","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shared/management/grpc/sync_message_versions.go","lineNumber":18,"sourceCode":"package grpc\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n)\n\ntype SyncMessageVersion uint16\n\nconst (\n\tBase SyncMessageVersion = iota\n\tComponentNetworkMap\n)\n\nconst DefaultSyncMessageVersion = Base\nconst HighestSyncMessageVersion = ComponentNetworkMap\n\nvar ErrorUnrecognizedSyncMessageVersion = errors.New(\"unrecognized SyncMessageVersion\")\n\nfunc ValidateSyncMessageVersion(v *int) error {\n\t// empty list == we support all available versions\n\tif v == nil {\n\t\treturn nil\n\t}\n\tif *v < 0 || *v > int(HighestSyncMessageVersion) {\n\t\treturn fmt.Errorf(\"sync message version must between 0 and %d, %w\", HighestSyncMessageVersion, ErrorUnrecognizedSyncMessageVersion)\n\t}\n\treturn nil\n}\n\n// returns SyncMessage version from config, or highest available version if the config is missing or\n// base if it is invalid\n// the assumption is ValidateSyncMessageVersion() has been called before using SyncMessageVersionFromConfig()\nfunc SyncMessageVersionFromConfig(v *int) SyncMessageVersion {\n\tif v == nil {\n\t\treturn DefaultSyncMessageVersion","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/shared/management/grpc/sync_message_versions.go#L1-L36","documentation":"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.","triggerScenarios":"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.","commonSituations":"Downgraded agent/management using config from a newer version; custom integrations pinning a sync version; experimental builds referencing not-yet-shipped versions.","solutions":["Leave the version nil (or Base) to use the default negotiation","Clamp the requested value to HighestSyncMessageVersion before validating","Upgrade the component that expects the newer sync version"],"exampleFix":"// before\nv := 5\nerr := grpc.ValidateSyncMessageVersion(&v)\n\n// after\nv := int(grpc.HighestSyncMessageVersion)\nerr := grpc.ValidateSyncMessageVersion(&v)","handlingStrategy":"validation","validationCode":"v := requestedVersion\nif v > int(grpc.HighestSyncMessageVersion) {\n\tv = int(grpc.HighestSyncMessageVersion)\n}\nif err := grpc.ValidateSyncMessageVersion(&v); err != nil {\n\treturn err\n}","typeGuard":"func isValidSyncVersion(v int) bool {\n\treturn v >= 0 && v <= int(grpc.HighestSyncMessageVersion)\n}","tryCatchPattern":"if err := grpc.ValidateSyncMessageVersion(&v); err != nil {\n\tif errors.Is(err, grpc.ErrorUnrecognizedSyncMessageVersion) {\n\t\t// fall back to the default version and retry\n\t}\n\treturn err\n}","preventionTips":["Prefer nil (support-all) or DefaultSyncMessageVersion over hardcoded numbers","Never copy version numbers between deployments","Bounds-check user-supplied versions against HighestSyncMessageVersion"],"tags":["grpc","versioning","sync","management"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}