tailscale/tailscale · error

macOS Screen Time is blocking network access: %w

Error message

macOS Screen Time is blocking network access: %w

What it means

Thrown by the ts2021 control-plane dialer when a dial/upgrade attempt fails AND the connection was observed to be intercepted by a local proxy (both LocalAddr and RemoteAddr are loopback, i.e. macOS proxyd). On macOS, Screen Time's 'Access to Web Content' restriction routes traffic through Apple's proxyd, which can silently block connections to Tailscale's coordination server. The error wraps the underlying network failure and marks the 'macos-screen-time' health Warnable (ImpactsConnectivity=true) unhealthy.

Source

Thrown at control/controlhttp/client.go:455

	// On macOS, see if Screen Time is blocking things.
	if runtime.GOOS == "darwin" {
		var proxydIntercepted atomic.Bool // intercepted by macOS webfilterproxyd
		origDialer := dialer
		dialer = func(ctx context.Context, network, address string) (net.Conn, error) {
			c, err := origDialer(ctx, network, address)
			if err != nil {
				return nil, err
			}
			if isLoopback(c.LocalAddr()) && isLoopback(c.RemoteAddr()) {
				proxydIntercepted.Store(true)
			}
			return c, nil
		}
		defer func() {
			if retErr != nil && proxydIntercepted.Load() {
				a.HealthTracker.SetUnhealthy(macOSScreenTime, nil)
				retErr = fmt.Errorf("macOS Screen Time is blocking network access: %w", retErr)
			} else {
				a.HealthTracker.SetHealthy(macOSScreenTime)
			}
		}()
	}

	tr := netutil.NewDefaultTransport()
	defer tr.CloseIdleConnections()
	if optACEHost != "" {
		// If using ACE, we don't want to use any HTTP proxy.
		// ACE is already a tunnel+proxy.
		// TODO(tailscale/corp#32483): use system proxy too?
		tr.Proxy = nil
		tr.DialContext = dialer
	} else {
		if buildfeatures.HasUseProxy {
			tr.Proxy = a.getProxyFunc()
			if set, ok := feature.HookProxySetTransportGetProxyConnectHeader.GetOk(); ok {

View on GitHub (pinned to 6e0912f979)

Solutions

1. Disable the restriction: System Settings > Screen Time > Content & Privacy > Access to Web Content > Unrestricted (or allow the control server URL)
2. If MDM-managed, ask the admin to exempt the Tailscale control host from the web-content filter
3. Toggle Screen Time off temporarily to confirm the diagnosis, then re-enable and allowlist
4. As a developer, surface the health Warnable to the user instead of retrying — the block persists until settings change

// Pre-check the environment before relying on control connectivity on darwin:
if runtime.GOOS == "darwin" && screenTimeRestrictsWeb() {
    warnUser("Screen Time may block the control connection; see System Settings > Screen Time")
}

conn, err := d.Dial(ctx)
if err != nil {
    if strings.Contains(err.Error(), "macOS Screen Time is blocking network access") {
        // Environmental block; retrying will not help until the user changes settings.
        return showScreenTimeGuidance(err)
    }
    return err
}

When it happens

Trigger: Running on darwin with Screen Time Content & Privacy Restrictions enabled, calling the controlhttp Dialer so that origDialer returns a conn where isLoopback(c.LocalAddr()) && isLoopback(c.RemoteAddr()) sets proxydIntercepted, and then tryURLUpgrade returns a non-nil retErr; the deferred check rewrites the error to this message.

Common situations: Macs under family/child Screen Time accounts or MDM profiles with 'Limit Web Content'/'Allowed Websites Only'; regression appears after a macOS upgrade re-enables Screen Time; CI Macs with content filters installed.

Related errors

• errNotUsingTailscale
• tailscale version not found in output
• no matching certificate
• failed refresh apk repository indexes: %w, output: %s
• can't open the Tailscale page in App Store: %w, output: %s

AI-assisted analysis of tailscale/tailscale@6e0912f979 (2026-08-18). Data as JSON: /api/errors/43ba0c55fc790115. Report an issue: GitHub.