{"record":{"id":"6427731d0d000133","repo":"netbirdio/netbird","slug":"engine-not-started","errorCode":null,"errorMessage":"engine not started","messagePattern":"engine not started","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"client/embed/embed.go","lineNumber":34,"sourceCode":"\twgnetstack \"golang.zx2c4.com/wireguard/tun/netstack\"\n\n\t\"github.com/netbirdio/netbird/client/iface\"\n\t\"github.com/netbirdio/netbird/client/iface/netstack\"\n\t\"github.com/netbirdio/netbird/client/internal\"\n\t\"github.com/netbirdio/netbird/client/internal/auth\"\n\t\"github.com/netbirdio/netbird/client/internal/peer\"\n\t\"github.com/netbirdio/netbird/client/internal/profilemanager\"\n\tsshcommon \"github.com/netbirdio/netbird/client/ssh\"\n\t\"github.com/netbirdio/netbird/client/system\"\n\t\"github.com/netbirdio/netbird/shared/management/domain\"\n\tmgmProto \"github.com/netbirdio/netbird/shared/management/proto\"\n\t\"github.com/netbirdio/netbird/util/capture\"\n)\n\nvar (\n\tErrClientAlreadyStarted = errors.New(\"client already started\")\n\tErrClientNotStarted     = errors.New(\"client not started\")\n\tErrEngineNotStarted     = errors.New(\"engine not started\")\n\tErrConfigNotInitialized = errors.New(\"config not initialized\")\n)\n\nconst (\n\t// PeerStatusConnected indicates the peer is in connected state.\n\tPeerStatusConnected = peer.StatusConnected\n)\n\n// PeerConnStatus is a peer's connection status.\ntype PeerConnStatus = peer.ConnStatus\n\n// Client manages a netbird embedded client instance.\ntype Client struct {\n\tdeviceName string\n\tconfig     *profilemanager.Config\n\tmu         sync.Mutex\n\tcancel     context.CancelFunc\n\tsetupKey   string","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/embed/embed.go#L16-L52","documentation":"The !result.Valid branch in forwardWithHeaderAuth (middleware.go:478). validateSessionToken completed successfully (no transport error) but the validator judged the session invalid — for OIDC tokens this is management's ValidateSession returning Valid=false (group access revoked, session expired server-side); for local methods the Ed25519 signature/claims check failed. The captured data is seeded with whatever identity info came back, then the client gets 401.","triggerScenarios":"Presenting a well-formed header session token whose session is no longer authorized: user removed from the group granting access, session expired per the domain's SessionExpiration, session revoked in management, or a signature that parses but does not verify against the domain key.","commonSituations":"Access revoked while an automation kept using the old token; token older than the configured session expiration; group/policy changes in management making ValidateSession deny; the operator tightened the service's allowed groups.","solutions":["Re-authenticate to get a new session token; if the denial is group-based, request access to the required group first.","Inspect management's 'Session validation denied' debug log (domain, denied_reason, user_id) to see exactly why Valid was false.","If sessions expire too fast for your workload, raise the domain's session expiration when registering it.","Confirm the token is being sent to the same domain it was issued for."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Client-side: track token issue time and drop it before the domain's\n// session expiration so you re-auth proactively.\nfunc tokenFresh(issuedAt time.Time, ttl time.Duration) bool {\n    return time.Since(issuedAt) < ttl\n}","typeGuard":null,"tryCatchPattern":"resp, err := client.Do(req)\nif err == nil && resp.StatusCode == http.StatusUnauthorized {\n    // Well-formed token but denied (revoked/expired/group loss):\n    // re-authenticate through the domain's flow; retrying the same token cannot succeed.\n}","preventionTips":["Treat 401 on a previously working token as 're-auth', never as 'retry'.","Keep group membership aligned with the service's access policy in management.","Refresh tokens on a schedule shorter than the domain's SessionExpiration.","Use management's 'Session validation denied' logs (denied_reason) for root cause."],"tags":["proxy","session-token","authorization","authentication"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}