What causes "startup check: management not connected" in netbirdio/netbird?

Run 'netbird status -d' (or check daemon logs) for the exact management connect error

startup check: management not connected

Error message

startup check: management not connected

What it means

Thrown by checkStartup (client/cmd/status.go:297). The FullStatus snapshot is present, but fullStatus.GetManagementState().GetConnected() is false: the agent's connection to the management service (control plane) is down or still being established. Without management the agent cannot receive network maps, so startup cannot be declared complete.

Source

Thrown at client/cmd/status.go:297

	daemonStatus := internal.StatusType(resp.GetStatus())
	switch daemonStatus {
	case internal.StatusIdle, internal.StatusConnecting, internal.StatusConnected:
		return nil
	case internal.StatusNeedsLogin, internal.StatusLoginFailed, internal.StatusSessionExpired:
		return fmt.Errorf("readiness check: daemon status is %s", daemonStatus)
	default:
		return fmt.Errorf("readiness check: unexpected daemon status %q", daemonStatus)
	}
}

func checkStartup(resp *proto.StatusResponse) error {
	fullStatus := resp.GetFullStatus()
	if fullStatus == nil {
		return fmt.Errorf("startup check: no full status available")
	}

	if !fullStatus.GetManagementState().GetConnected() {
		return fmt.Errorf("startup check: management not connected")
	}

	if !fullStatus.GetSignalState().GetConnected() {
		return fmt.Errorf("startup check: signal not connected")
	}

	var relayCount, relaysConnected int
	for _, r := range fullStatus.GetRelays() {
		uri := r.GetURI()
		if !strings.HasPrefix(uri, "rel://") && !strings.HasPrefix(uri, "rels://") {
			continue
		}
		relayCount++
		if r.GetAvailable() {
			relaysConnected++
		}
	}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Run 'netbird status -d' (or check daemon logs) for the exact management connect error
Verify the management URL resolves and is reachable: curl -v https://<management-host>
Fix host DNS / firewall egress to the management port, then retry the check (the daemon reconnects on its own)
If TLS is the cause, trust the CA on the host or fix the certificate the management serves

Defensive patterns

Strategy: retry

Validate before calling

// preflight the management endpoint before expecting startup to pass
u, err := url.Parse(config.ManagementURL.String())
if err == nil {
    if _, derr := net.DialTimeout("tcp", u.Host, 3*time.Second); derr != nil {
        log.Warnf("management %s unreachable before startup check", u.Host)
    }
}

Prevention

Pin management connectivity (DNS, 443 egress, TLS trust) before deploying agents
Retry startup checks with a deadline; management connect is normally transient during boot
Watch 'netbird status -d' for the underlying management error instead of guessing

When it happens

Trigger: 'netbird status --check startup' while the daemon's gRPC channel to the management URL is connecting, broken, or repeatedly failing: management URL unreachable, DNS failure for the management host, TLS/mTLS failure, management service restarting, or IdP outage during the connect flow.

Common situations: On-prem management down or behind a firewall that drops 443; misconfigured --management-url; self-signed cert not trusted by the agent; DNS resolver broken on the host (agent rewrote resolv.conf previously and did not restore it).

Related errors

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