netbirdio/netbird · warning

stop: %w

Error message

stop: %w

What it means

Returned by Client.Stop when ConnectClient.Stop completes but reports an error tearing down the engine (interface removal, firewall/DNS cleanup, management disconnect). The stop path already ran to completion, so this error means cleanup was imperfect, not that the client is still running: c.connect is cleared either way.

Source

Thrown at client/embed/embed.go:331

	if c.cancel != nil {
		c.cancel()
		c.cancel = nil
	}

	done := make(chan error, 1)
	connect := c.connect
	go func() {
		done <- connect.Stop()
	}()

	select {
	case <-ctx.Done():
		c.connect = nil
		return ctx.Err()
	case err := <-done:
		c.connect = nil
		if err != nil {
			return fmt.Errorf("stop: %w", err)
		}
		return nil
	}
}

// GetConfig returns a copy of the internal client config.
func (c *Client) GetConfig() (profilemanager.Config, error) {
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.config == nil {
		return profilemanager.Config{}, ErrConfigNotInitialized
	}
	return *c.config, nil
}

// Dial dials a network address in the netbird network.
// Not applicable if the userspace networking mode is disabled.
func (c *Client) Dial(ctx context.Context, network, address string) (net.Conn, error) {

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Inspect the wrapped error to identify the subsystem that failed cleanup.
2. Verify host state manually if the error mentions the interface or firewall (ip link, nft list ruleset) and clean up leftovers.
3. Treat the client as stopped regardless: Stop is called once and c.connect is nil afterwards; create a new Client to restart.
4. Enable debug logs before stopping to capture the engine-side teardown reason.

stopCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
if err := client.Stop(stopCtx); err != nil {
    // client is stopped regardless; log and verify host state manually if needed
    log.Warnf("stop reported cleanup error: %v", err)
}

When it happens

Trigger: Client.Stop after a partially started or degraded engine: firewall/DNS cleanup fails because system state changed underneath, interface already removed externally, or management disconnect errors surface during teardown.

Common situations: Stopping after a failed Start; host networking state mutated by other tooling (iptables flushed, interface deleted manually); stopping while the management connection is already broken.

Related errors

• stop error after context done. Stop error: %w. Context done:
• expose manager not available
• service is not up
• client not initialized
• engine not started

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