gravitational/teleport · error

the background item was not enabled within the timeout

Error message

the background item was not enabled within the timeout

What it means

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.

Source

Thrown at lib/vnet/daemon/client_darwin.go:166

		log.DebugContext(ctx, "Registering the daemon has failed", "service_status", status)
		return -1, trace.Errorf("registering daemon failed, %s", C.GoString(result.error_description))
	}

	return ServiceStatus(result.service_status), nil
}

// waitForEnablement periodically checks if the status of the daemon has changed to
// [serviceStatusEnabled]. This happens when the user approves the login item in system settings.
func waitForEnablement(ctx context.Context, bundlePath string) error {
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()

	// It should be less than receiveTunTimeout in the vnet package
	// so that the user sees the error about the background item first.
	const waitingForEnablementTimeout = 50 * time.Second
	ctx, cancel := context.WithTimeoutCause(ctx, waitingForEnablementTimeout,
		errors.New("the background item was not enabled within the timeout"))
	defer cancel()

	for {
		select {
		case <-ctx.Done():
			return context.Cause(ctx)
		case <-ticker.C:
			switch status := daemonStatus(bundlePath); status {
			case ServiceStatusEnabled:
				return nil
			case ServiceStatusRequiresApproval:
				// Continue waiting for the user to approve the login item.
			case ServiceStatusNotRegistered, ServiceStatusNotFound:
				// Something happened to the service since we started waiting, abort.
				return trace.Errorf("encountered unexpected service status %q", status)
			default:
				return trace.Errorf("encountered unknown service status %q", status)
			}

View on GitHub (pinned to 1283425b60)

Solutions

1. Open System Settings > Login Items and enable the tsh.app background item, then run tsh vnet start again.
2. If MDM-managed, approve the login item via MDM (e.g. ServiceManagement policy / Skip Login Item approval profile).
3. Re-run the command; registration persists, so the next attempt only needs the enablement step.

// check login item status before waiting for enablement
status := vnetdaemon.DaemonStatus(bundlePath)
if status == vnetdaemon.ServiceStatusNotRegistered {
    return errors.New("daemon not registered; run registration first")
}

if err := client.RegisterAndCall(ctx, bundlePath, cfg); err != nil {
    if strings.Contains(err.Error(), "the background item was not enabled within the timeout") {
        fmt.Println("Enable tsh.app under System Settings > Login Items, then try again.")
    }
    return trace.Wrap(err)
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• could not connect to the VNet daemon within the timeout
• VNet is already running
• either identifier or team identifier is missing in code sign
• XPC connection interrupted
• code signing requirement failed

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/51aa1954cdc32fb9. Report an issue: GitHub.