netbirdio/netbird · error

engine is not initialized

Error message

engine is not initialized

What it means

Returned by extendAuthSession in the Android client when the profile config and gRPC connection snapshot exist but the connection's Engine() is nil. The engine is the component that owns the WireGuard interface and the management session, so a nil engine means the client object exists but its network engine was never started or has already been stopped. Without it there is no session to extend and no way to forward the renewed token.

Source

Thrown at client/android/session.go:287

}

func (c *Client) endExtend() {
	c.extendMu.Lock()
	defer c.extendMu.Unlock()
	if c.extendCancel != nil {
		c.extendCancel()
		c.extendCancel = nil
	}
}

func (c *Client) extendAuthSession(ctx context.Context, urlOpener URLOpener, isAndroidTV bool) error {
	cfg, cfgPath, cc := c.authSnapshot()
	if cfg == nil || cc == nil {
		return fmt.Errorf("engine is not running")
	}
	engine := cc.Engine()
	if engine == nil {
		return fmt.Errorf("engine is not initialized")
	}

	authClient, err := auth.NewAuth(ctx, cfg.PrivateKey, cfg.ManagementURL, cfg)
	if err != nil {
		return fmt.Errorf("failed to create auth client: %v", err)
	}
	defer authClient.Close()

	// Passing the config path makes the flow pick up the login_hint: an extend
	// renews the session of the account already signed in, so it must not stop to
	// offer a choice.
	a := NewAuthWithConfig(ctx, cfg, cfgPath)
	tokenInfo, err := a.foregroundGetTokenInfo(authClient, urlOpener, isAndroidTV)
	if err != nil {
		return fmt.Errorf("interactive sso login failed: %v", err)
	}

	if _, err := engine.ExtendAuthSession(ctx, tokenInfo.GetTokenToUse()); err != nil {

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Wait for the connected/running state (e.g. the connect callback or OnClientConnected) before invoking the extend API
2. If it persists after connect completes, restart the client session: call down/up (or Service_Stop then Service_Start) so a fresh engine is created
3. Check that only one extend is in flight — beginExtend rejects concurrent extends with a different error, but a stuck extend can leave the client in a bad state; call endExtend/cancel path
4. If reproducible, capture logs for whether Stop() ran between connect and extend (engine set to nil on teardown)

Example fix

// before: extend invoked as soon as the screen showing the expiry warning appears
client.extendAuthSession(ctx, opener, false)

// after: only extend once the client reports a running engine
if cc := client.conn(); cc == nil || cc.Engine() == nil {
    // not connected yet; retry after the connect callback fires
    return
}
client.extendAuthSession(ctx, opener, false)

// Java/Android binding side: only offer the extend action when the engine is live
// (the Go API surface: c.conn() != nil && c.conn().Engine() != nil)
// Via the mobile SDK this maps to checking the connected state callback first.
if (!isClientConnected()) { // set from the connect callback, cleared on disconnect
    showRetryWhenConnected();
    return;
}
netbirdClient.extendAuthSession(opener, isTv);

// Go, if calling extendAuthSession from other client code:
func (c *Client) canExtend() bool {
    cfg, _, cc := c.authSnapshot()
    return cfg != nil && cc != nil && cc.Engine() != nil
}

When it happens

Trigger: Calling the Android SessionExtend/mobile binding right after startup before the connect flow finished creating the engine; calling extend after the client was disconnected (engine torn down) while a stale client connection object is still returned by authSnapshot; race between a stop/login-required transition and the extend call.

Common situations: Android app calls extend immediately after process restore (background restore, app swipe-away and relaunch) before netbird up/connect completes; extending a session after logout or after a crash-recovery path that nils the engine; TV flows where the UI button is enabled before the service reports connected.

Related errors

• engine is not running
• engine is not running
• session extend already in progress
• failed to create auth client: %v
• interactive sso login failed: %v

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