netbirdio/netbird · error

engine is not initialized

Error message

engine is not initialized

What it means

The non-ErrHeaderAuthFailed branch of handleHeaderAuthError (middleware.go:505): the header scheme's Authenticate errored for infrastructure reasons (lookup service unreachable, internal dependency failing) rather than bad credentials. The middleware logs 'header auth infrastructure error', tags the captured data with OriginAuth, and returns 502 'authentication service unavailable'.

Source

Thrown at client/internal/connect.go:522

	return relayCfg.GetUrls(), token
}

func (c *ConnectClient) Engine() *Engine {
	if c == nil {
		return nil
	}
	var e *Engine
	c.engineMutex.Lock()
	e = c.engine
	c.engineMutex.Unlock()
	return e
}

// GetLatestSyncResponse returns the latest sync response from the engine.
func (c *ConnectClient) GetLatestSyncResponse() (*mgmProto.SyncResponse, error) {
	engine := c.Engine()
	if engine == nil {
		return nil, errors.New("engine is not initialized")
	}

	syncResponse, err := engine.GetLatestSyncResponse()
	if err != nil {
		return nil, fmt.Errorf("get latest sync response: %w", err)
	}

	if syncResponse == nil {
		return nil, errors.New("sync response is not available")
	}

	return syncResponse, nil
}

// SetLogLevel sets the log level for the firewall manager if the engine is running.
func (c *ConnectClient) SetLogLevel(level log.Level) {
	engine := c.Engine()
	if engine == nil {

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Read the logged 'header auth infrastructure error: %v' — it names the actual failing dependency.
2. Restore/restart the backend the header scheme depends on (typically the management gRPC endpoint).
3. Add or verify health checks so the proxy surfaces dependency outage before requests hit this path.
4. Retry after the dependency is healthy; credentials are unaffected.

// 502 'authentication service unavailable' from header auth = dependency
// outage. Back off and retry; do not rotate credentials in response.
var lastErr error
for i := 0; i < 3; i++ {
    resp, lastErr = client.Do(req)
    if lastErr == nil && resp.StatusCode != http.StatusBadGateway {
        break
    }
    time.Sleep((1 << i) * 500 * time.Millisecond)
}

When it happens

Trigger: scheme.Authenticate returning any error other than ErrHeaderAuthFailed: the backend it queries (management gRPC or other identity source) unreachable, timing out, or returning an unexpected error while validating the presented header credential.

Common situations: Management outage while header-authenticated traffic keeps flowing; gRPC channel idle-broken behind a load balancer; dependency upgrade changed an error path so a previously-handled failure now escapes as a generic error.

Related errors

• sync response is not available
• client not started
• tun module not available
• an earlier read of the policy table has not returned
• host argument required

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