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

Retry the check briefly - signal connect normally completes right after management connect

startup check: signal not connected

Error message

startup check: signal not connected

What it means

Thrown by checkStartup (client/cmd/status.go:301). FullStatus is present and management is connected, but fullStatus.GetSignalState().GetConnected() is false: the agent is not connected to the signal service that brokers peer handshakes. The signal URL is distributed by management, so this is a data-plane bootstrap failure after control-plane success.

Source

Thrown at client/cmd/status.go:301

	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++
		}
	}

	if relayCount > 0 && relaysConnected == 0 {
		return fmt.Errorf("startup check: no relay servers available (0/%d connected)", relayCount)
	}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Retry the check briefly - signal connect normally completes right after management connect
Check the signal service health (docker ps / systemctl, /healthcheck endpoint on the signal)
Open outbound access to the signal host/port advertised by management
Inspect 'netbird status -d' or daemon logs for the signal dial error

Defensive patterns

Strategy: retry

Prevention

Keep the signal service monitored (healthcheck endpoint) in self-hosted setups
Allow egress to the signal host/port that management advertises
Expect signal to lag management by a few seconds during startup; poll, do not single-shot

When it happens

Trigger: 'netbird status --check startup' when the signal service is down, the signal URL/port learned from management is unreachable (egress firewall), or the signal TLS handshake fails. Also transiently true for the few seconds between management connect and signal connect.

Common situations: Self-hosted signal container stopped or crashed; firewall allowing 443 to management but blocking the signal port (default 10000); hostname resolution for the signal endpoint failing on the agent host.

Related errors

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