Troubleshooting common issues

Here are the issues we see most often in support, with the fixes ranked from simplest to deepest. Start with the quick fix at the top of each section.

Device shows as offline in the app

Quick fix: unplug the ProxyBox, wait 10 seconds, plug it back in. 80% of "offline" reports resolve on a power-cycle.

If that doesn't work: check the router. Is your home internet working? Can your phone browse the web on Wi-Fi? If no, fix the internet first.

If the internet is fine but the box is still offline: the ProxyBox's Wi-Fi credentials may be wrong (e.g., you changed your Wi-Fi password without re-pairing). Use the app's "Change Wi-Fi" option in device settings to re-provision.

Proxy isn't routing my traffic

Open the app, go to the Proxy tab, tap "Test It." The app makes a real request through the proxy and reports which IP it came from. You should see your home's public IP.

If the test fails or shows a datacenter IP, things to check:

• Is the ProxyBox online? (Dashboard shows green dot.)
• Is your client using the correct proxy URL + credentials? Copy them fresh from the app's Proxy tab.
• Is your client set to route traffic through the proxy? (In most apps, "system proxy" doesn't apply, you have to configure the app specifically.)
• Does the destination accept HTTP proxy connections? Some corporate firewalls block them.

Bluetooth pairing fails with "Encryption Error"

This is an iOS Bluetooth bond state issue. Fix:

1. Open iOS Settings, then Bluetooth.
2. Find any entry named "ProxyBox-xxxx."
3. Tap the info icon, then "Forget This Device."
4. Return to the ProxyBox app and try pairing again.

Root cause: iOS remembers Bluetooth bonds indefinitely. If a ProxyBox was previously paired and then reset, the phone still has the old bond info, which conflicts with the new handshake.

If the iOS app keeps failing, try one of the alternate pairing paths described in Three ways to pair: Web Bluetooth from a desktop browser at proxybox.us/pair, or the captive Wi-Fi portal (join ProxyBox-Setup-XXXX from any phone or laptop).

Speed test shows slow download/upload

Speed tests through the ProxyBox measure your home internet's speed, not the Pi's throughput. The Pi can comfortably handle 100+ Mbps. If your home connection is 50 Mbps, the speed test will cap at 50 Mbps, that's physics, not a ProxyBox problem.

To diagnose: run a speed test on your laptop plugged directly into the router (bypassing the ProxyBox). If that's slow too, it's your ISP. If that's fast but through-the-ProxyBox is slow, check that the ProxyBox isn't on Wi-Fi in a weak-signal location.

Device heartbeat seems stuck in the past

Some of the dashboard metrics (device uptime, last heartbeat time) are cached for performance. Pull down to refresh, that forces a re-fetch.

If it's still stuck 10+ minutes after refresh, the Pi isn't successfully heartbeating. Usually means local network issue. Reboot the Pi.

Last updated: 2026-04-29