{"record":{"id":"5501617f23d707e3","repo":"netbirdio/netbird","slug":"engine-is-not-initialized","errorCode":null,"errorMessage":"engine is not initialized","messagePattern":"engine is not initialized","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/internal/connect.go","lineNumber":522,"sourceCode":"\treturn relayCfg.GetUrls(), token\n}\n\nfunc (c *ConnectClient) Engine() *Engine {\n\tif c == nil {\n\t\treturn nil\n\t}\n\tvar e *Engine\n\tc.engineMutex.Lock()\n\te = c.engine\n\tc.engineMutex.Unlock()\n\treturn e\n}\n\n// GetLatestSyncResponse returns the latest sync response from the engine.\nfunc (c *ConnectClient) GetLatestSyncResponse() (*mgmProto.SyncResponse, error) {\n\tengine := c.Engine()\n\tif engine == nil {\n\t\treturn nil, errors.New(\"engine is not initialized\")\n\t}\n\n\tsyncResponse, err := engine.GetLatestSyncResponse()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"get latest sync response: %w\", err)\n\t}\n\n\tif syncResponse == nil {\n\t\treturn nil, errors.New(\"sync response is not available\")\n\t}\n\n\treturn syncResponse, nil\n}\n\n// SetLogLevel sets the log level for the firewall manager if the engine is running.\nfunc (c *ConnectClient) SetLogLevel(level log.Level) {\n\tengine := c.Engine()\n\tif engine == nil {","sourceCodeStart":504,"sourceCodeEnd":540,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/internal/connect.go#L504-L540","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the logged 'header auth infrastructure error: %v' — it names the actual failing dependency.","Restore/restart the backend the header scheme depends on (typically the management gRPC endpoint).","Add or verify health checks so the proxy surfaces dependency outage before requests hit this path.","Retry after the dependency is healthy; credentials are unaffected."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// 502 'authentication service unavailable' from header auth = dependency\n// outage. Back off and retry; do not rotate credentials in response.\nvar lastErr error\nfor i := 0; i < 3; i++ {\n    resp, lastErr = client.Do(req)\n    if lastErr == nil && resp.StatusCode != http.StatusBadGateway {\n        break\n    }\n    time.Sleep((1 << i) * 500 * time.Millisecond)\n}","preventionTips":["Monitor the header scheme's backing service (usually management gRPC) health.","Read the 'header auth infrastructure error' log to identify the exact dependency before acting.","Keep credentials stable across these errors; they are not the cause.","Restart the proxy to rebuild gRPC channels after prolonged management outages."],"tags":["proxy","header-auth","infrastructure","availability"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}