Troubleshooting

Split any problem into two questions first: is traffic reaching Chute at all (a takeover problem), and is Chute able to forward it (a forwarding problem)? The live traffic view answers this — open the Dashboard (iOS) or the main window's Traffic tab (Mac) and browse: if nothing appears, Chute is not receiving the traffic; if connections appear but fail, Chute cannot forward them. The two halves have completely different fixes.

Nothing appears: takeover problems

Chute iOS

• The switch refuses to turn on and the Config bar shakes — no configuration is selected. Tap the Config bar, tap a configuration so it shows a checkmark, then Done ("Please select configuration first").
• The VPN permission dialog was declined — toggle again and approve it. If the VPN profile is stuck (the switch flips back immediately), use Reset VPN Configuration in the app's settings; the next start re-creates the profile and re-prompts.
• Another VPN app is connected — iOS runs one VPN tunnel at a time. Disconnect the other app (or disable its on-demand rules, which can silently re-grab the tunnel).

Chute Mac

• System Proxy is on but an app ignores it — many tools (terminal programs in particular) do not honor the system proxy. Point them at Chute's listener explicitly (Copy Shell Export Command in the menu does this for shells), or use Enhanced Mode, which captures traffic at the network layer.
• Enhanced Mode won't start — the network extension or helper needs approval; see Enhanced Mode troubleshooting for the exact System Settings paths, the "System Extension Blocked" case, and the stale-VPN reset.
• Traffic to LAN addresses bypasses Chute by design — check skip-proxy and tun-excluded-routes in Miscellaneous Options before assuming takeover is broken.

Connections appear but fail: forwarding problems

• Isolate the path. Switch your policy group to DIRECT: if pages load direct but fail through the proxy, the problem is the proxy server — wrong host/port/credentials/cipher, or the server is down. Run a latency test on the group; a policy that never passes the test while others do names the culprit.
• The wrong rule matches. Look at the matched rule of a failing connection in the live traffic view, then re-read the rule evaluation order: rules are evaluated in two passes, so for hostname-based requests a later non-IP rule can match before an earlier IP rule. no-resolve and FINAL placement are the usual suspects.
• DNS answers look wrong. Verify the DNS section: on encrypted DNS, make sure the DoH/DoT server itself is reachable without the proxy; purge the DNS cache after changing servers (iOS Control Panel switch, flushDNS from a script, or DELETE /api/dns/cache on the HTTP control API).
• UDP-dependent apps misbehave — confirm the selected policy supports UDP relay (see the capability matrix in Proxy Policy) and remember Tailscale does not forward ICMP, so ping through an exit node stays silent.

HTTPS decryption doesn't decrypt

• The CA must be installed and trusted — two separate steps on iOS; the second (Settings → General → About → Certificate Trust Settings) is the one everyone misses. See Install and trust the CA certificate.
• The host must match the [MITM] hostname list — only declared hosts are decrypted, and only on port 443 unless a :port/:0 suffix says otherwise.
• Some apps pin their certificates and will fail while decrypted — exclude their hosts with a - prefix rather than fighting them.
• QUIC/HTTP-3 cannot be decrypted — see block-quic for steering compatible clients back to TCP.

Reading the logs

When the sections above don't settle it, the log usually does:

• Raise the log level temporarily: loglevel = verbose (revert afterwards — verbose is slow).
• Chute Mac: the main window's Log tab. Chute iOS: the Dashboard, or GET /api/logs on the HTTP control API.
• Warnings are the interesting lines: unknown policies, rejected options, and unparsable rules are all logged as warnings when the configuration loads.