{"record":{"id":"90f34bd40a1933d7","repo":"netbirdio/netbird","slug":"startup-w","errorCode":null,"errorMessage":"startup: %w","messagePattern":"startup: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/embed/embed.go","lineNumber":293,"sourceCode":"\t\tif err := client.Run(run, \"\"); err != nil {\n\t\t\tclientErr <- err\n\t\t}\n\t}()\n\n\tselect {\n\tcase <-startCtx.Done():\n\t\t// ConnectClient.Stop now cancels its own run context and waits for the\n\t\t// run loop to tear the engine down, so this cancel() is no longer\n\t\t// required to break the deadlock and could be removed. It is kept as a\n\t\t// defensive belt-and-suspenders: cancelling the parent context first\n\t\t// guarantees the run loop is unblocked even if Stop's contract regresses.\n\t\tcancel()\n\t\tif stopErr := client.Stop(); stopErr != nil {\n\t\t\treturn fmt.Errorf(\"stop error after context done. Stop error: %w. Context done: %w\", stopErr, startCtx.Err())\n\t\t}\n\t\treturn startCtx.Err()\n\tcase err := <-clientErr:\n\t\treturn fmt.Errorf(\"startup: %w\", err)\n\tcase <-run:\n\t}\n\n\tc.connect = client\n\tc.cancel = cancel\n\n\treturn nil\n}\n\n// Stop gracefully stops the client.\n// Pass a context with a deadline to limit the time spent waiting for the engine to stop.\nfunc (c *Client) Stop(ctx context.Context) error {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tif c.connect == nil {\n\t\treturn ErrClientNotStarted\n\t}","sourceCodeStart":275,"sourceCodeEnd":311,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/embed/embed.go#L275-L311","documentation":"Returned by Client.Start when the ConnectClient run loop exits with an error before the engine finishes starting (the 'startup' channel path). This is the engine's permanent/startup backoff error: interface creation failure, management stream failure, or any engine subsystem that aborts during initial bring-up. It is distinct from the context-deadline path: here the run loop itself failed.","triggerScenarios":"Client.Start where newWgIface or engine start fails: no TUN/netstack available in the environment, MTU rejected again at engine level, management connection drops mid-start, or privileged operations fail when NoUserspace=true without root.","commonSituations":"Running with NoUserspace=true inside a container without NET_ADMIN/root; a host where the netstack/TUN setup fails (seccomp blocking the syscall); management connection reset during initial sync; version skew between embedded client and management protocol.","solutions":["Unwrap the error to find which subsystem failed: 'new wg interface' points at TUN/netstack/privileges, stream errors at management.","If NoUserspace=true, ensure the process has the required privileges (root/CAP_NET_ADMIN) and kernel WireGuard support; otherwise keep userspace mode.","Check management connectivity and protocol compatibility, then retry Start with a new client.","Enable debug logging (Options.LogLevel \"debug\") to get the engine-side reason, which is often logged rather than returned."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := client.Start(ctx); err != nil {\n    if strings.Contains(err.Error(), \"startup:\") {\n        log.Debug-level engine logs carry the real cause; unwrap and classify before retrying\n    }\n}","preventionTips":["Run with debug logging during integration to capture engine-side startup failures.","Ensure privileges (root/NET_ADMIN) when using NoUserspace=true."],"tags":["startup","engine","network","embed"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}