What causes "create auth client: %w" in netbirdio/netbird?

Inspect the wrapped error: parse failures point to PrivateKey/ManagementURL, TLS errors at the PKI setup.

create auth client: %w

Error message

create auth client: %w

What it means

Returned by Client.Start when auth.NewAuth fails to build the management gRPC client. This covers loading/deriving the peer's private key material, parsing the management URL into a gRPC target, and preparing the TLS connection to the management server. The client never attempts a login when this error is returned.

Source

Thrown at client/embed/embed.go:260

	c.mu.Lock()
	defer c.mu.Unlock()
	if c.connect != nil {
		return ErrClientAlreadyStarted
	}

	ctx, cancel := context.WithCancel(internal.CtxInitState(context.Background()))
	defer func() {
		if c.connect == nil {
			cancel()
		}
	}()

	// nolint:staticcheck
	ctx = context.WithValue(ctx, system.DeviceNameCtxKey, c.deviceName)

	authClient, err := auth.NewAuth(ctx, c.config.PrivateKey, c.config.ManagementURL, c.config)
	if err != nil {
		return fmt.Errorf("create auth client: %w", err)
	}
	defer authClient.Close()

	if err, _ := authClient.Login(ctx, c.setupKey, c.jwtToken); err != nil {
		return fmt.Errorf("login: %w", err)
	}
	client := internal.NewConnectClient(ctx, c.config, c.recorder)
	client.SetSyncResponsePersistence(true)

	// either startup error (permanent backoff err) or nil err (successful engine up)
	// TODO: make after-startup backoff err available
	run := make(chan struct{})
	clientErr := make(chan error, 1)
	go func() {
		if err := client.Run(run, ""); err != nil {
			clientErr <- err
		}
	}()

View on GitHub (pinned to 93e97f4bf1)

Solutions

Inspect the wrapped error: parse failures point to PrivateKey/ManagementURL, TLS errors at the PKI setup.
Print/verify config via Client.GetConfig (ManagementURL, key presence) before Start.
Regenerate the private key or re-register the peer if the key material is suspect.
Ensure the management URL includes scheme and port and is reachable from the host.

Defensive patterns

Strategy: validation

Validate before calling

cfg, err := client.GetConfig()
if err == nil {
    if u, uerr := url.Parse(cfg.ManagementURL.String()); uerr != nil || u.Scheme == "" || u.Host == "" {
        return fmt.Errorf("management URL invalid: %s", cfg.ManagementURL)
    }
}

Try / catch

if err := client.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "create auth client") {
        // config/PKI problem: fix config, recreate client; retrying Start will not help
    }
}

Prevention

Always include scheme in ManagementURL (https://...).
Do not hand-edit stored private keys; regenerate and re-register instead.

When it happens

Trigger: Client.Start with a config whose ManagementURL is empty or malformed (bad scheme/host), a PrivateKey that cannot be parsed as a WireGuard key, or an environment where the TLS credentials/PKI setup fails.

Common situations: Typical after fixing auth: the management URL lacks the scheme (api.example.com instead of https://api.example.com), a hand-edited config file holds a truncated or base64-corrupted private key, or an updated management server changed its certificate setup so client credential preparation fails.

Related errors

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