What causes "parse overlay address %q: %w" in netbirdio/netbird?

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.

netbirdio/netbird · critical

parse overlay address %q: %w

Error message

parse overlay address %q: %w

What it means

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.

Source

Thrown at client/internal/connect.go:594

	c.engineMutex.Lock()
	c.persistSyncResponse = enabled
	c.engineMutex.Unlock()

	engine := c.Engine()
	if engine != nil {
		engine.SetSyncResponsePersistence(enabled)
	}
}

// createEngineConfig converts configuration received from Management Service to EngineConfig
func createEngineConfig(key wgtypes.Key, config *profilemanager.Config, peerConfig *mgmProto.PeerConfig, logPath string) (*EngineConfig, error) {
	nm := false
	if config.NetworkMonitor != nil {
		nm = *config.NetworkMonitor
	}
	wgAddr, err := wgaddr.ParseWGAddress(peerConfig.Address)
	if err != nil {
		return nil, fmt.Errorf("parse overlay address %q: %w", peerConfig.Address, err)
	}

	if !config.DisableIPv6 {
		if err := wgAddr.SetIPv6FromCompact(peerConfig.GetAddressV6()); err != nil {
			log.Warn(err)
		}
	}

	engineConf := &EngineConfig{
		WgIfaceName:                   config.WgIface,
		WgAddr:                        wgAddr,
		IFaceBlackList:                config.IFaceBlackList,
		DisableIPv6Discovery:          config.DisableIPv6Discovery,
		WgPrivateKey:                  key,
		WgPort:                        config.WgPort,
		NetworkMonitor:                nm,
		SSHKey:                        []byte(config.SSHKey),
		NATExternalIPs:                config.NATExternalIPs,

View on GitHub (pinned to 93e97f4bf1)

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.

Example fix

// before
wgAddr, err := wgaddr.ParseWGAddress(peerConfig.Address)
if err != nil {
    return nil, fmt.Errorf("parse overlay address %q: %w", peerConfig.Address, err)
}

// after (fail with actionable context naming the server as the source)
wgAddr, err := wgaddr.ParseWGAddress(peerConfig.Address)
if err != nil {
    return nil, fmt.Errorf("management assigned invalid overlay address %q (re-login or check the account IP pool): %w", peerConfig.Address, err)
}

Defensive patterns

Strategy: validation

Validate before calling

// validate the management-assigned address before building engine config
func validOverlayAddress(addr string) bool {
    prefix, err := netip.ParsePrefix(addr)
    return err == nil && prefix.Addr().Is4() && prefix.Bits() >= 8 && prefix.Bits() <= 32
}

Try / catch

engineConf, err := createEngineConfig(key, config, peerConfig, logPath)
if err != nil {
    if strings.Contains(err.Error(), "parse overlay address") {
        // the %q value came verbatim from management: report it with both
        // versions; re-login pulls a fresh PeerConfig
    }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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