Home/Docs/macOS Guide/Troubleshooting and limits (macOS)

macOS Guide

Troubleshooting and limits (macOS)

Fix common ProxyBridge problems on macOS: the extension needs approval, nothing in Connections, a rule does not match, domain rules, proxy errors, UDP and HTTP/3, DNS and VPN conflicts. Includes every message you may see and the known limits.

Troubleshooting and limits

Start with the first section. Most problems are one of three things: the extension is not approved, the rule does not match the program, or the proxy refuses the connection.

Start here: is the connection matching a rule?

  1. Open the main window and the Connections tab. Make sure Proxy > Enable Traffic Logging is ticked.
  2. Start the program (or open a page) again. Find its line.
  3. Read the end of the line:
The line ends with Meaning
SOCKS5 host:port or HTTP host:port The rule matched and the connection went to that proxy. If it still does not work, the problem is the proxy: read the Activity Logs tab
Direct No rule matched, or a DIRECT rule did. Look at the name in the line and compare it with the rule: The rule does not match
BLOCK A BLOCK rule matched
No line at all The program's traffic never reaches ProxyBridge: Nothing appears in Connections

The extension needs approval or a restart

ProxyBridge routes traffic through a system extension. macOS makes you approve it once.

Signs: the Activity Logs say Extension needs user approval in System Settings, or Extension failed: ..., or the Connections tab stays empty after the first start.

What to do:

  1. Open System Settings. Look for a message that ProxyBridge's extension was blocked, under Privacy & Security (scroll to the Security section and click Allow), and for the extension under General > Login Items & Extensions > Network Extensions. Make sure ProxyBridge is switched on. Enter your password if macOS asks.
  2. macOS also asks once to add a network configuration (a proxy configuration for ProxyBridge). Click Allow. If you clicked Don't Allow, the app writes Failed to save preferences: ... in the Activity Logs. Quit and open ProxyBridge again and allow it.
  3. Quit ProxyBridge (⌘Q) and open it again.

The step-by-step with screenshots is in Install on macOS.

To see the state of the extension, run in Terminal:

systemextensionsctl list

Look for com.interceptsuite.ProxyBridge.extension with [activated enabled]. [activated waiting for user] means approval is still needed. [terminated waiting to uninstall on reboot] means an old copy is waiting for a restart.

After an update, the new extension replaces the old one. macOS can ask for approval again, and sometimes needs a restart to finish. The command line says macOS will finish activating the system extension after a restart. Restart the Mac and open ProxyBridge.

macOS version. ProxyBridge needs macOS 13 Ventura or later, on Apple silicon or Intel. Older versions are not supported.

Nothing appears in Connections

Cause What to check
Enable Traffic Logging is off Tick it in the Proxy menu. With it off the window shows no connections and no extension messages
The window was hidden While the window is hidden or minimized ProxyBridge does not read the log. Open the window; you see the most recent lines
The extension is not running See the section above. Activity Logs should show Proxy tunnel started after start-up
Another ProxyBridge is running The command line and the window control the same extension. Only one runs at a time. See Command line
macOS is not giving the traffic to ProxyBridge Rare. Some traffic is handled by macOS itself and never reaches an extension. A program that does not appear cannot be routed

The program does not appear at all

If other programs show up in Connections but yours does not:

  • It may not have opened a connection yet. Make it do something that needs the network.
  • It may make its connections from a helper process with another name (browsers, Electron apps). Look for the helper's name in the log.
  • It may connect only to your own Mac (loopback) or to local services that macOS does not hand to an extension. Check by connecting to an outside address.
  • It may use a VPN or a network extension of its own that macOS applies before ProxyBridge.

The rule does not match

Compare the line in Connections with your rule, character by character.

Cause Fix
The rule uses the app name, the connection comes from a helper Use the helper's name from the log, or a wildcard: *chrome*, com.microsoft.VSCode*
A pattern for the exact bundle identifier is too narrow com.google.Chrome does not match com.google.Chrome.helper. Add *
Path in the field Paths never match. Use the process name or bundle identifier
The name is a script, not a program Use the interpreter (python3, node, java)
The rule is switched off Check the On switch
The protocol is wrong A TCP rule never matches UDP, and the other way round
The action names a proxy that was deleted or never existed (imported rule) Edit the rule and pick a proxy. The Activity Logs show A rule routes to a proxy that no longer exists, its traffic is going direct
An earlier rule matched first See How rules are matched. Specific rules and filtered * rules win in list order; a catch-all (* with no limits) is only the fallback
A host entry has a typo, or uses CIDR CIDR (10.0.0.0/8) is not supported. Use 10.*.*.* or a range. A host list uses ; only
A port entry has a typo 80- or 9000-8000 is ignored. If no valid entry is left, the rule matches no port
The program opened its connection before you added the rule Only new connections are redirected. Restart the program
A UDP rule has a host or port limit They are ignored for UDP; a rule with * and a limit never matches UDP

Domain rules do not match

Domain names are known from the app's DNS lookups, so a domain rule needs a seen lookup. See Domain names need plain DNS. The checklist:

  1. Does the Connections line show the host name (not an IP address)? If it shows an IP, ProxyBridge did not see the lookup.
  2. Does the app use DNS over HTTPS or DNS over TLS (a browser's "Secure DNS", an encrypted DNS profile, some VPNs)? Turn it off, or match by IP.
  3. Was the lookup made before ProxyBridge started, or long ago? The names are kept in memory only and are empty at start. Reload the page, or restart the app.
  4. Does the app connect to an IP address it already knows? Use an IP rule.
  5. Is the entry written correctly? *.example.com also covers example.com; example alone matches nothing.
  6. Is the DNS proxy switched on? Activity Logs should show DNS proxy enabled at start-up. If it says DNS proxy setup failed: ..., domain rules and send hostname do not work.

The proxy does not work

The error is in the Activity Logs tab. First press Test in Proxy Settings: it tells you which step fails.

A connection whose proxy is unreachable, or that rejects it, is closed, not sent direct. This is deliberate: traffic you chose to proxy never goes around the proxy. A proxy that accepts the connection and then says nothing is cut after 20 seconds.

Symptom Fix
SOCKS5 greeting write failed: ... The proxy cannot be reached: wrong host or port, nothing is listening, or a firewall. Run Test
SOCKS5 greeting response failed, SOCKS5 invalid greeting response, SOCKS5 invalid version: N The proxy answered with something that is not SOCKS5. A very common cause: the proxy type is SOCKS5 but the port is an HTTP proxy (or the other way round). Check the type
SOCKS5 no acceptable auth method: N The proxy needs an authentication method ProxyBridge did not offer, for example it requires a password and none is set in the proxy
SOCKS5 auth failed Wrong user name or password
SOCKS5 connect rejected, REP=0x05 (connection refused) and other REP codes The proxy works, but could not reach the destination. The reason in brackets is the proxy's
HTTP CONNECT failed: HTTP/1.1 407 ... The proxy needs a user name and password, or rejected yours
HTTP CONNECT failed: HTTP/1.1 403 ... or 502 ... The proxy refuses or cannot reach that host or port. Some proxy tools can be set to refuse CONNECT to certain ports
Web pages load but HTTPS shows certificate errors Not a ProxyBridge problem. Trust the proxy tool's CA certificate in macOS (Keychain Access) or in the browser
It worked, then stopped The proxy tool was closed, or its listener changed. Press Test

UDP, QUIC and HTTP/3

Problem Explanation
UDP can't go through an HTTP proxy, UDP traffic for that rule is going direct HTTP proxies cannot carry UDP. Use a SOCKS5 proxy, or set the rule's protocol to TCP and add a separate UDP BLOCK rule if direct UDP is not acceptable
SOCKS5 UDP ASSOCIATE rejected, REP=0x07 (command not supported) or ... failed The SOCKS5 proxy does not support UDP ASSOCIATE. Most do not, including SSH -D tunnels and Tor. Check test 4 of the proxy test
The proxy test says UDP works but QUIC does not QUIC and HTTP/3 need a proxy that relays raw UDP datagrams properly. Nexus Proxy is built for testing this
A browser is not proxied although there is a TCP rule The browser used QUIC (UDP 443). Add a UDP rule, or BLOCK the browser's UDP so it falls back to TCP
A UDP rule with ports does not narrow anything UDP rules match the app only. Hosts and ports are ignored
UDP relay error: ..., UDP write error: ..., UDP read error: ... The proxy's UDP relay stopped answering or refused a datagram. The app's UDP flow then times out by itself

Each proxied UDP flow keeps a proxy connection open until it has been idle for 120 seconds; macOS gives ProxyBridge no signal when a program closes its socket.

Name lookups fail while another VPN or DNS tool runs

ProxyBridge turns on a DNS proxy so that it can learn which names belong to which addresses. It only passes your lookups on to the resolver macOS chose, and reads the answers. One user reported (issue #264) that, with the ProxyBridge DNS proxy and a VPN client (aTrust) both active, every name lookup timed out, and that switching off the ProxyBridge DNS entry in System Settings (Network, in the filters list; the exact place can differ between macOS versions) fixed it. Other VPNs we tried (a WireGuard VPN whose gateway is the DNS server) worked normally. The cause is being investigated. If you hit this:

  • Turn off Proxy > Enable DNS. ProxyBridge then stops using the DNS proxy and switches its own entry off, so the VPN or the other tool can use macOS's one DNS proxy slot. Host name rules and the send hostname option stop working (they depend on the lookups). IP rules, and BLOCK and DIRECT rules, keep working. The setting is saved per profile.
  • Please tell us on the issue about the VPN or DNS tool, your macOS version, and the output of scutil --dns.

Programs that close their sending side and wait

A connection where the program half-closes (it finishes sending and keeps reading, as nc does when its input ends) loses the answer. macOS closes the connection in both directions when the program finishes sending, so ProxyBridge cannot deliver a reply. Ordinary web, API and SSH traffic is not affected. When testing with nc, keep its input open.

Messages and what to do

From the extension (written in the Activity Logs with a UTC time):

Message Meaning
Proxy configs updated: N config(s) The extension received your proxy list (information)
A rule routes to a proxy that no longer exists, its traffic is going direct A rule's action points to a missing proxy. Written once per missing proxy
UDP can't go through an HTTP proxy, UDP traffic for that rule is going direct See UDP
unsupported proxy type: X The proxy has a type other than socks5 or http (only possible in a hand-edited profile)
SOCKS5 greeting write failed, SOCKS5 greeting response failed, SOCKS5 invalid greeting response, SOCKS5 invalid version: N, SOCKS5 no acceptable auth method: N The SOCKS5 handshake failed before authentication. See The proxy does not work
SOCKS5 credentials too long, SOCKS5 auth write failed, SOCKS5 auth response failed, SOCKS5 auth failed The user name or password is over 255 bytes, or the proxy rejected it
SOCKS5 destination name too long The host name is longer than 255 bytes
SOCKS5 connect write failed, SOCKS5 connect rejected, REP=0xNN (reason), SOCKS5 connect failed: reason The proxy would not connect to the target. reason can be general failure, not allowed by ruleset, network unreachable, host unreachable, connection refused, TTL expired, command not supported or address type not supported
HTTP CONNECT write failed, HTTP CONNECT request encoding failed, HTTP CONNECT failed: <status line> The HTTP proxy refused the tunnel. Any 2xx status counts as success. The status line is shown. invalid status line or response headers incomplete or too large mean it is not an HTTP proxy, or its reply is longer than 16 KB
Failed to open client flow: ..., Client read error, Client write error, Proxy read error, Proxy write error The connection broke while data was moving. Normal resets (a program that just closed) are not reported
SOCKS5 UDP greeting failed, SOCKS5 UDP greeting response failed, SOCKS5 UDP greeting response invalid, SOCKS5 UDP no acceptable auth method, SOCKS5 UDP credentials too long, SOCKS5 UDP auth write failed, SOCKS5 UDP auth response failed, SOCKS5 UDP auth rejected The same as the TCP messages, for the UDP control connection
SOCKS5 UDP ASSOCIATE failed: ..., SOCKS5 UDP ASSOCIATE rejected, REP=0xNN (reason), SOCKS5 UDP ASSOCIATE returned no relay port The proxy does not offer UDP, or refused it
UDP read error, UDP write error, UDP relay error, UDP response write error, Domain name too long: N bytes A problem moving UDP datagrams, see UDP

From the app (written with the short local time):

Message Meaning
Extension installed successfully, Configuration saved, Proxy tunnel started, DNS proxy enabled, Proxy configs sent: N config(s), Loaded N rule(s) from local storage Start-up steps (information)
Extension needs user approval in System Settings Approve the extension, see above
Extension failed: ... macOS refused to install or start the extension. The reason follows
Failed to load managers: ..., Failed to save preferences: ..., Failed to reload preferences: ..., Failed to start tunnel: ... macOS refused the network configuration, or the tunnel did not start. Quit, open ProxyBridge again, and allow the prompt
DNS proxy setup failed: ... The DNS proxy could not be enabled (domain rules and send-hostname will not work)
Failed to encode proxy configs The proxy list could not be sent. Re-save the proxies
Proxy stopped and extension memory cleared You quit the app: the rules and proxies were removed from the extension

Limits

What Limit
macOS 13 Ventura or later, Apple silicon and Intel
Proxies, rules No limit in the app. The command line refuses profiles over 100 proxies or 5000 rules
Target hosts ; separated, IPv4 wildcards need 4 parts, no CIDR, no ? wildcard
Proxy handshake 20 seconds, then the connection is closed
HTTP proxy reply Headers up to 16 KB
SOCKS5 user name and password 255 bytes each
SOCKS5 host name 255 bytes
UDP datagram Up to 65,507 bytes. Fragmented SOCKS5 UDP datagrams are dropped
Proxied UDP flow Closed after 120 seconds without traffic
After a program finishes sending 3 seconds to flush, then the connection closes
Names learned from DNS 1024 addresses, 8 names each; the oldest are forgotten first. Kept in memory only, cleared on start and stop
A name sent to a proxy Only if seen in the last 5 minutes, and only made of letters, digits, ., - and _
DNS the extension sees Ordinary DNS over UDP. DNS over TCP, HTTPS and TLS are not seen
Log 500 lines kept, 100 handed to the window per second
Existing connections Not changed; only new ones
Always direct ProxyBridge's own traffic, and traffic with no rule
UDP rules Match the app only
Half-closing programs Cannot receive an answer (macOS closes the connection)

Still stuck?

Collect this and open an issue on GitHub:

sw_vers
systemextensionsctl list

plus the ProxyBridge version (Help > About ProxyBridge), a screenshot of the Activity Logs tab, and the rule and proxy settings with passwords removed. For crashes, add the report from Console.app, under Crash Reports, and the lines that mention "ProxyBridge".