{"record":{"id":"43ba0c55fc790115","repo":"tailscale/tailscale","slug":"macos-screen-time-is-blocking-network-access-w","errorCode":null,"errorMessage":"macOS Screen Time is blocking network access: %w","messagePattern":"macOS Screen Time is blocking network access: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"control/controlhttp/client.go","lineNumber":455,"sourceCode":"\n\t// On macOS, see if Screen Time is blocking things.\n\tif runtime.GOOS == \"darwin\" {\n\t\tvar proxydIntercepted atomic.Bool // intercepted by macOS webfilterproxyd\n\t\torigDialer := dialer\n\t\tdialer = func(ctx context.Context, network, address string) (net.Conn, error) {\n\t\t\tc, err := origDialer(ctx, network, address)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t\tif isLoopback(c.LocalAddr()) && isLoopback(c.RemoteAddr()) {\n\t\t\t\tproxydIntercepted.Store(true)\n\t\t\t}\n\t\t\treturn c, nil\n\t\t}\n\t\tdefer func() {\n\t\t\tif retErr != nil && proxydIntercepted.Load() {\n\t\t\t\ta.HealthTracker.SetUnhealthy(macOSScreenTime, nil)\n\t\t\t\tretErr = fmt.Errorf(\"macOS Screen Time is blocking network access: %w\", retErr)\n\t\t\t} else {\n\t\t\t\ta.HealthTracker.SetHealthy(macOSScreenTime)\n\t\t\t}\n\t\t}()\n\t}\n\n\ttr := netutil.NewDefaultTransport()\n\tdefer tr.CloseIdleConnections()\n\tif optACEHost != \"\" {\n\t\t// If using ACE, we don't want to use any HTTP proxy.\n\t\t// ACE is already a tunnel+proxy.\n\t\t// TODO(tailscale/corp#32483): use system proxy too?\n\t\ttr.Proxy = nil\n\t\ttr.DialContext = dialer\n\t} else {\n\t\tif buildfeatures.HasUseProxy {\n\t\t\ttr.Proxy = a.getProxyFunc()\n\t\t\tif set, ok := feature.HookProxySetTransportGetProxyConnectHeader.GetOk(); ok {","sourceCodeStart":437,"sourceCodeEnd":473,"githubUrl":"https://github.com/tailscale/tailscale/blob/6e0912f97994f927632b34ae9e63b53d6516a6ac/control/controlhttp/client.go#L437-L473","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Disable the restriction: System Settings > Screen Time > Content & Privacy > Access to Web Content > Unrestricted (or allow the control server URL)","If MDM-managed, ask the admin to exempt the Tailscale control host from the web-content filter","Toggle Screen Time off temporarily to confirm the diagnosis, then re-enable and allowlist","As a developer, surface the health Warnable to the user instead of retrying — the block persists until settings change"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-check the environment before relying on control connectivity on darwin:\nif runtime.GOOS == \"darwin\" && screenTimeRestrictsWeb() {\n    warnUser(\"Screen Time may block the control connection; see System Settings > Screen Time\")\n}","typeGuard":null,"tryCatchPattern":"conn, err := d.Dial(ctx)\nif err != nil {\n    if strings.Contains(err.Error(), \"macOS Screen Time is blocking network access\") {\n        // Environmental block; retrying will not help until the user changes settings.\n        return showScreenTimeGuidance(err)\n    }\n    return err\n}","preventionTips":["Surface the health Warnable (code macos-screen-time) in your UI instead of raw errors","Do not auto-retry this error; it persists until Screen Time settings change","Document the required Screen Time exemption for managed Mac deployments"],"tags":["macos","screen-time","content-filter","darwin","network","proxyd"],"backgroundTag":"os-content-filter-blocking-network","analyzedSha":"6e0912f97994f927632b34ae9e63b53d6516a6ac","analyzedAt":"2026-08-18T08:17:25.280Z","contentChangedAt":"2026-08-18T08:17:25.280Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}