{"record":{"id":"51aa1954cdc32fb9","repo":"gravitational/teleport","slug":"the-background-item-was-not-enabled-within-the-tim","errorCode":null,"errorMessage":"the background item was not enabled within the timeout","messagePattern":"the background item was not enabled within the timeout","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"lib/vnet/daemon/client_darwin.go","lineNumber":166,"sourceCode":"\n\t\tlog.DebugContext(ctx, \"Registering the daemon has failed\", \"service_status\", status)\n\t\treturn -1, trace.Errorf(\"registering daemon failed, %s\", C.GoString(result.error_description))\n\t}\n\n\treturn ServiceStatus(result.service_status), nil\n}\n\n// waitForEnablement periodically checks if the status of the daemon has changed to\n// [serviceStatusEnabled]. This happens when the user approves the login item in system settings.\nfunc waitForEnablement(ctx context.Context, bundlePath string) error {\n\tticker := time.NewTicker(time.Second)\n\tdefer ticker.Stop()\n\n\t// It should be less than receiveTunTimeout in the vnet package\n\t// so that the user sees the error about the background item first.\n\tconst waitingForEnablementTimeout = 50 * time.Second\n\tctx, cancel := context.WithTimeoutCause(ctx, waitingForEnablementTimeout,\n\t\terrors.New(\"the background item was not enabled within the timeout\"))\n\tdefer cancel()\n\n\tfor {\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn context.Cause(ctx)\n\t\tcase <-ticker.C:\n\t\t\tswitch status := daemonStatus(bundlePath); status {\n\t\t\tcase ServiceStatusEnabled:\n\t\t\t\treturn nil\n\t\t\tcase ServiceStatusRequiresApproval:\n\t\t\t\t// Continue waiting for the user to approve the login item.\n\t\t\tcase ServiceStatusNotRegistered, ServiceStatusNotFound:\n\t\t\t\t// Something happened to the service since we started waiting, abort.\n\t\t\t\treturn trace.Errorf(\"encountered unexpected service status %q\", status)\n\t\t\tdefault:\n\t\t\t\treturn trace.Errorf(\"encountered unknown service status %q\", status)\n\t\t\t}","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/gravitational/teleport/blob/1283425b60ec5f60d509ba4c791183d452923ff7/lib/vnet/daemon/client_darwin.go#L148-L184","documentation":"Raised in waitForEnablement (lib/vnet/daemon/client_darwin.go:166) as the context.Cause of a 50-second timeout. After registering the daemon login item, the client polls every second for the status to become ServiceStatusEnabled (user approval in System Settings). If the user does not approve the background item within 50 seconds, this error is returned.","triggerScenarios":"RegisterAndCall registers the daemon for the first time, status is ServiceStatusRequiresApproval, and the user does not enable the tsh.app background item under System Settings > Login Items within 50 seconds (the poll loop never sees ServiceStatusEnabled).","commonSituations":"First-time tsh VNet setup where the user misses or ignores the System Settings prompt; enterprise MDM policies delaying login-item approval; user unable to find the setting; not-registered/not-found statuses hitting the timeout branch.","solutions":["Open System Settings > Login Items and enable the tsh.app background item, then run tsh vnet start again.","If MDM-managed, approve the login item via MDM (e.g. ServiceManagement policy / Skip Login Item approval profile).","Re-run the command; registration persists, so the next attempt only needs the enablement step."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// check login item status before waiting for enablement\nstatus := vnetdaemon.DaemonStatus(bundlePath)\nif status == vnetdaemon.ServiceStatusNotRegistered {\n    return errors.New(\"daemon not registered; run registration first\")\n}","typeGuard":null,"tryCatchPattern":"if err := client.RegisterAndCall(ctx, bundlePath, cfg); err != nil {\n    if strings.Contains(err.Error(), \"the background item was not enabled within the timeout\") {\n        fmt.Println(\"Enable tsh.app under System Settings > Login Items, then try again.\")\n    }\n    return trace.Wrap(err)\n}","preventionTips":["Prompt the user clearly to approve the Login Item before starting the 50s window.","In MDM environments, pre-approve the login item via policy so no manual approval is needed.","Surface progress messaging so the user knows approval is pending."],"tags":["macos","login-items","timeout","vnet"],"backgroundTag":"background-item-enablement-timeout","analyzedSha":"1283425b60ec5f60d509ba4c791183d452923ff7","analyzedAt":"2026-09-02T04:06:41.601Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}