{"record":{"id":"070c45ebb7a5dc5d","repo":"netbirdio/netbird","slug":"parse-overlay-address-q-w","errorCode":null,"errorMessage":"parse overlay address %q: %w","messagePattern":"parse overlay address %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"client/internal/connect.go","lineNumber":594,"sourceCode":"\tc.engineMutex.Lock()\n\tc.persistSyncResponse = enabled\n\tc.engineMutex.Unlock()\n\n\tengine := c.Engine()\n\tif engine != nil {\n\t\tengine.SetSyncResponsePersistence(enabled)\n\t}\n}\n\n// createEngineConfig converts configuration received from Management Service to EngineConfig\nfunc createEngineConfig(key wgtypes.Key, config *profilemanager.Config, peerConfig *mgmProto.PeerConfig, logPath string) (*EngineConfig, error) {\n\tnm := false\n\tif config.NetworkMonitor != nil {\n\t\tnm = *config.NetworkMonitor\n\t}\n\twgAddr, err := wgaddr.ParseWGAddress(peerConfig.Address)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"parse overlay address %q: %w\", peerConfig.Address, err)\n\t}\n\n\tif !config.DisableIPv6 {\n\t\tif err := wgAddr.SetIPv6FromCompact(peerConfig.GetAddressV6()); err != nil {\n\t\t\tlog.Warn(err)\n\t\t}\n\t}\n\n\tengineConf := &EngineConfig{\n\t\tWgIfaceName:                   config.WgIface,\n\t\tWgAddr:                        wgAddr,\n\t\tIFaceBlackList:                config.IFaceBlackList,\n\t\tDisableIPv6Discovery:          config.DisableIPv6Discovery,\n\t\tWgPrivateKey:                  key,\n\t\tWgPort:                        config.WgPort,\n\t\tNetworkMonitor:                nm,\n\t\tSSHKey:                        []byte(config.SSHKey),\n\t\tNATExternalIPs:                config.NATExternalIPs,","sourceCodeStart":576,"sourceCodeEnd":612,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/internal/connect.go#L576-L612","documentation":"createEngineConfig failed to parse the overlay IP address that management assigned to this peer (peerConfig.Address, for example '100.64.0.1/16') via netip.ParsePrefix. The %q shows the exact malformed string. Without a valid CIDR the agent cannot build EngineConfig, so connect/login aborts and the tunnel never comes up.","triggerScenarios":"wgaddr.ParseWGAddress(peerConfig.Address) fails because management sent an empty address, a bare IP without the /prefix, a value with whitespace or garbage characters, or an IPv6 literal where v4 is required; also protobuf version skew where the agent reads a field the management version fills differently.","commonSituations":"Account IP pool or network range misconfigured so assignment produced an invalid value; pool exhausted and an empty address slipped through; self-hosted management older/newer than the agent formatting the field differently; a corrupted local profile replaying an old PeerConfig after management changes.","solutions":["Inspect the quoted value in the message: empty means management never assigned an address (check the account's IP pool in the management UI); missing /mask or garbage points at a management-side formatting bug.","Run a fresh login (netbird down then netbird up) to pull a new PeerConfig instead of replaying a stale one.","Align agent and management versions - mixed versions can serialize the address field differently; upgrade the older side.","On self-hosted management, verify the account network range (default 100.64.0.0/16) is intact and the peer has an assigned IP in the dashboard.","Report with both versions and the quoted value if it persists - the string came verbatim from the server."],"exampleFix":"// before\nwgAddr, err := wgaddr.ParseWGAddress(peerConfig.Address)\nif err != nil {\n    return nil, fmt.Errorf(\"parse overlay address %q: %w\", peerConfig.Address, err)\n}\n\n// after (fail with actionable context naming the server as the source)\nwgAddr, err := wgaddr.ParseWGAddress(peerConfig.Address)\nif err != nil {\n    return nil, fmt.Errorf(\"management assigned invalid overlay address %q (re-login or check the account IP pool): %w\", peerConfig.Address, err)\n}","handlingStrategy":"validation","validationCode":"// validate the management-assigned address before building engine config\nfunc validOverlayAddress(addr string) bool {\n    prefix, err := netip.ParsePrefix(addr)\n    return err == nil && prefix.Addr().Is4() && prefix.Bits() >= 8 && prefix.Bits() <= 32\n}","typeGuard":null,"tryCatchPattern":"engineConf, err := createEngineConfig(key, config, peerConfig, logPath)\nif err != nil {\n    if strings.Contains(err.Error(), \"parse overlay address\") {\n        // the %q value came verbatim from management: report it with both\n        // versions; re-login pulls a fresh PeerConfig\n    }\n}","preventionTips":["Keep agent and management versions compatible; the address field format is part of their contract.","On self-hosted management, validate the account IP range before inviting peers.","Re-login after management-side network changes instead of replaying stored profiles.","Log the raw PeerConfig.Address on parse failure so the malformed value is always captured."],"tags":["configuration","netip","management","overlay","connect"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}