Linux Guide
Troubleshooting and limits (Linux)
Fix common ProxyBridge problems on Linux: it will not start, a rule does not match, domain rules, UDP and HTTP/3, proxy errors, containers and WSL. Includes every message you may see and the known limits.
Troubleshooting and limits
Most problems fall into three groups: ProxyBridge does not start, a program is not matched by a rule, or the proxy cannot be used. The Activity Logs tab (or --verbose 1 on the command line) says what ProxyBridge itself is complaining about, and the Connections tab says what happened to each connection.
Start here: is the connection matching a rule?
- Open the Connections tab and start the program (or reconnect it).
- Find its lines. What do they say?
| You see | It means | Go to |
|---|---|---|
| No lines for the program | ProxyBridge never saw its connections: it started them before ProxyBridge did, the program is in a container, or logging is off | No lines |
via DIRECT |
No rule matched (or a rule says Direct) | The rule does not match the program |
via SOCKS5 ... or via HTTP ... |
It is being proxied. If the proxy shows nothing, check the proxy | The proxy does not work |
via BLOCK |
A Block rule matched | Rules |
Also check the Enable ProxyBridge switch (Proxy menu): if it is off, nothing is redirected. And remember that only new connections are affected: restart the program after you change a rule.
The window cannot reach the service
The window runs as you and talks to the ProxyBridge service (see Install on Linux). If it cannot, it shows a message and does nothing else:
| Message | Cause and fix |
|---|---|
The ProxyBridge service is not running. |
Start it: sudo systemctl enable --now proxybridge. If it fails, journalctl -u proxybridge says why. On a system without systemd, run sudo ProxyBridge --daemon, or start the window with sudo (it then runs the engine itself) |
not allowed: only root and members of the group 'proxybridge' may control ProxyBridge |
Your user is not in the group: sudo usermod -aG proxybridge $USER. It takes effect at once; just start the window again. The service logs the refusal (refused a connection from user ...) |
no permission to use the ProxyBridge service socket /run/proxybridge/ctl.sock |
The socket folder was changed. Restart the service: sudo systemctl restart proxybridge |
the program listening on ... does not belong to root; refusing to talk to it |
Something other than the real service owns the socket. The window refuses to send your proxy passwords to it. Stop that program and restart the service |
protocol mismatch: the service speaks N; update or restart ProxyBridge so both are the same version |
The window and the service are different versions (an update that did not restart the service). sudo systemctl restart proxybridge |
too many windows are connected |
16 windows are already open; close one |
Lost the connection to the ProxyBridge service. Trying to reconnect... (status bar) |
The service restarted or stopped. When it is back the window reconnects by itself and sends its configuration again (connected to the ProxyBridge service again). If it does not come back, systemctl status proxybridge |
Is the service running but nothing is routed? Check Start at Boot and that the window has been opened since: with Start at Boot off the service is idle until a window starts the engine, and closing the window stops routing again. See Settings.
ProxyBridge does not start
The window says Failed to start the ProxyBridge engine, or the command line prints ERROR: Failed to start ProxyBridge. The reason is in the Activity Logs (or with --verbose 1; for the service also journalctl -u proxybridge).
| Message | Cause and fix |
|---|---|
ProxyBridge needs root (CAP_BPF/CAP_SYS_ADMIN) to load its eBPF programs |
The engine was started without root. The window never starts it itself (the service does, as root); this appears for ProxyBridge --profile without sudo |
cgroup v2 is not mounted (need a unified hierarchy at /sys/fs/cgroup) |
Your system uses the old cgroup v1 layout. Check with stat -fc %T /sys/fs/cgroup (it must print cgroup2fs). Current Ubuntu, Debian, Fedora and Arch use v2. On an old system boot with systemd.unified_cgroup_hierarchy=1 |
loading the BPF programs failed (needs a kernel >= 5.11 with BTF and cgroup sock_addr support): ... |
The kernel is too old, or built without BTF or cgroup BPF. Check uname -r and that /sys/kernel/btf/vmlinux exists. The text after the colon is the kernel's own reason (for example Operation not permitted inside a restricted container, or a locked-down kernel) |
attach ... failed: ... |
The kernel refused one of the hooks. Same causes as above; another program using the same hooks can also be the reason |
relay: cannot listen on 127.0.0.1:N: ... |
A local port the relay needs is taken. It uses 24010 and 24011 and moves to the next free pair; this appears only if none work |
relay: could not raise the open file limit: ... |
The system will not let ProxyBridge open as many sockets as it wants. It still runs, with a lower limit on simultaneous connections |
cannot start: a rule uses a proxy but no proxy is configured |
Add a proxy, or change the rule |
too many rules (max N) |
A profile holds more rules than the engine accepts |
If nothing helps, run sudo ProxyBridge --profile ./test.pbprofile --verbose 3 with a one-rule profile; it prints everything the engine reports.
The program does not appear at all
- The program already had its connections open. Only new connections are seen. Restart the program.
- It runs in a container, a Flatpak sandbox with its own network, or another network namespace. See Containers and network namespaces.
- Traffic logging is off. Check Settings > Enable Traffic Logging.
- A log filter hides it. Open Proxy > Log Filters... and look for an Exclude filter that matches. See Connections and logs.
- The engine is stopped. The status bar must say
Engine: Running. - It does not use the network at all, or only talks to
127.0.0.1(local traffic is not logged unless a rule with Also proxy localhost traffic matches it).
The rule does not match the program
You see via DIRECT for a program that should be proxied.
- Is the process name right? Names are case-sensitive and are the file name of the program, not the title in the window. Use the name shown in the Connections tab.
python3is notpython3.12; a script runs as its interpreter. See Process names. - Helper processes. Browsers, Electron apps and package managers connect from helper processes with other names. Add the name you see in the log to the same rule (separate names with
;). - Is the rule enabled (check box ticked)? Is an earlier rule catching the connection first? The first matching rule wins, so a
*rule above hides the rules below. See Rule order. - Port and protocol.
80;443andTCPdo not match QUIC (UDP 443) or a service on another port. Check the destination port in the log line. - Target host. A rule for
*.example.comneeds the domain to be known; see Domain rules do not match. A rule for an address needs the exact address. - Launched from a different binary. A program started through a launcher script runs under the real binary's name (
firefox-bin,chrome). A pattern with a/compares the full path, which can also be too exact:/usr/bin/firefoxdoes not match a copy in/opt/firefox/firefox. - The connection was already open when you changed the rule. Restart the program.
Domain rules do not match
Rules for domain names depend on ProxyBridge seeing the program's own DNS answers. They cannot match when:
- The program uses DNS over HTTPS or TLS (Firefox "Secure DNS", Chrome "Secure DNS", systemd-resolved with DoT). Switch that off in the program, or use IP rules.
- The program connects to a hard-coded or cached address it never looked up.
- The destination is IPv6. Names are only learned from
AandCNAMErecords. - Two names share one address (shared hosting): the name looked up last wins, and a rule for either name matches.
- The rule says
*.github.comand the program connects togithub.comitself. Linux is stricter than Windows here; list both:github.com; *.github.com.
Also: a domain rule makes ProxyBridge route the DNS traffic of the matching programs through its relay so it can read the answers. This costs about 0.1 ms per lookup and only affects programs covered by a domain rule. Programs not covered are untouched.
The proxy does not work
First run Start Test in Proxy Settings...; it checks the proxy without involving your rules. See Test a proxy. Then look at the Activity Logs.
| Symptom or message | Fix |
|---|---|
relay: proxy SOCKS5 127.0.0.1:1080: connect to 127.0.0.1:1080 failed: Connection refused |
The proxy is not running, or the host or port is wrong |
... failed: Connection timed out |
A firewall drops the connection, or the proxy host is unreachable |
SOCKS5 authentication failed (wrong username or password) |
Wrong login |
SOCKS5 proxy rejected all auth methods (credentials required or not accepted) |
The proxy requires a login and none is set |
HTTP proxy authentication required (407) |
Same, for an HTTP proxy |
| The application hangs, then fails | The proxy accepted the connection but never answered; ProxyBridge gives up after 10 seconds. Other proxies are not affected |
| Pages load but the proxy tool shows nothing | The tool lists the traffic in another place (a different listener, or "invisible" mode). Check the Live Connections tab: bytes are moving through the proxy |
| HTTPS sites show certificate errors | You are intercepting. Import the tool's CA certificate into the application |
| Everything stops working when the rule uses the Burp or mitmproxy listener | The tool is not running. A failed proxy handshake closes the connection; it is never sent direct |
A connection whose proxy is unreachable or rejects it is closed, not sent direct. That is deliberate: traffic you chose to proxy never goes around the proxy.
UDP, QUIC and HTTP/3
| Problem | Explanation |
|---|---|
rule N sends UDP to HTTP proxy '...', which cannot carry UDP: that UDP traffic goes 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 |
relay: UDP associate failed: ... |
The SOCKS5 proxy does not support UDP ASSOCIATE. Most do not, including SSH -D tunnels and Tor. Check step 5 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 |
relay: UDP datagram dropped (...) |
A datagram could not be delivered, with the reason. If a proxy keeps refusing, ProxyBridge drops that flow's datagrams for 5 seconds before it tries again |
| A browser is not proxied although there is a TCP rule | The browser used QUIC (UDP 443). Add a UDP rule, or Block UDP 443 so the browser falls back to TCP |
| A program that opens many UDP sockets stops working through the proxy | A proxied UDP session stays open for 60 seconds after the last datagram, because the engine cannot see a program close its socket. A proxy that limits connections per client (Nexus Proxy: 500) refuses the rest |
A native IPv6 UDP send fails with EPERM |
An unconnected UDP socket sending to a native IPv6 address cannot be redirected (kernel limit). Most programs fall back to IPv4 |
UDP that is "decided" by the relay
The kernel itself decides rules with up to 4 ports, 4 IPv4 ranges and short host lists. A longer port list, a domain rule or an IPv6 pattern sends every UDP datagram of the matching program through the relay. This works, with two side effects when a UDP rule says Direct: the peer sees the relay's source port instead of the program's, and a UDP server that matches the same program has its replies re-sent from another port. Keep rules for UDP servers narrow: list ports as ranges, or name the destination, or put them in a rule of their own.
Containers and network namespaces
ProxyBridge only redirects traffic of programs in the host network namespace. Docker containers with their own network, Podman, LXC and ip netns are never redirected, on purpose (so ProxyBridge cannot affect other networks). To proxy a containerised program:
- run the container with
--network host, then match its process name as seen on the host, or - point the program itself at a proxy that is reachable from the container.
A program running inside a container with --network host is matched by its executable, like any other.
WSL
WSL1 and WSL2 are not supported: their kernels ship without BTF and cgroup BPF. Use a real Linux machine, a virtual machine or a cloud instance. In WSL2 you can instead use the Windows version of ProxyBridge on the Windows side.
Messages and what to do
Everything the Activity Logs tab or --verbose 1 can say, grouped:
| Message | Meaning |
|---|---|
ProxyBridge started (eBPF datapath, relay tcp:N udp:M) |
Running. N and M are the relay's local ports |
ProxyBridge stopped |
The engine was stopped cleanly |
process P serves proxy 'name': its own connections are sent direct, not back through the proxy |
A program on this computer listens on the proxy's address (Burp, ssh -D, Tor). It is exempted so rules cannot loop. Informational |
relay: no original destination for client ...:N, closing |
A connection reached the relay without the kernel having recorded where it was going (for example a program connected to the relay port directly). It is closed |
relay: connection limit (N) reached, dropping new connections |
Too many simultaneous connections. They are dropped until some close |
relay: handshake queue full (N), shedding new connections |
Proxy handshakes are queued up faster than they complete (a slow proxy). New ones are refused rather than waiting without end |
relay: SOCKS5 UDP control connection closed, dropping session for ... |
The proxy closed the connection that keeps a UDP association alive. The session is dropped; the next datagram opens a new one |
relay: UDP: no proxy configured (id N), dropping |
A UDP rule refers to a proxy that no longer exists. Pick a proxy in the rule |
relay: UDP cannot be proxied through HTTP proxy '...'; dropping UDP from ... |
The rule's proxy is an HTTP proxy. See UDP |
relay: SO_BINDTODEVICE lo failed (...); relying on destination address filtering |
The relay could not tie its UDP port to the loopback device. It still works, using address checks instead |
kernel has no SO_NETNS_COOKIE: connections from other network namespaces are not isolated |
An old kernel; containers might be redirected |
failed to apply rules to the kernel datapath |
The kernel refused the rule set. Run with --verbose 1 for the reason, and check the kernel log (dmesg) |
Limits
| What | Limit |
|---|---|
| Kernel | Linux 5.11 or newer with BTF and cgroup v2 |
| Privileges | Root |
| Proxies per profile | 255 |
| Rules per profile | 4096 |
| Target Host entries per rule | 1024 |
| Profile file size | 4 MiB |
| Log filters | 64 |
| Names learned from DNS | 32,768 addresses; the oldest are forgotten first |
| Proxied UDP sessions | 4096 in total, at most 2048 per program |
| A proxy that does not answer | 10 seconds, then the connection is closed |
| Handshake workers | start at 8, grow to 64; one proxy never holds more than 48 |
| UDP session idle time | 60 seconds |
| IPv6 | TCP and connected UDP work with IP rules; no domain matching; unconnected native-IPv6 UDP to a proxy fails closed |
IPV6_V6ONLY sockets |
Cannot connect to a proxied destination |
| Existing connections | Not changed; only new ones |
| Always direct | Loopback (unless a rule opts in), multicast, broadcast, reserved ranges, IPv6 link-local, DHCP (UDP 67 and 68) |
Still stuck?
Collect this and open an issue on GitHub:
uname -r
stat -fc %T /sys/fs/cgroup
ls -l /sys/kernel/btf/vmlinux
sudo ProxyBridge --version
plus the lines of the Activity Logs tab (--verbose 3 output on the command line) and the rule and proxy settings, with passwords removed.
