Most p2proxy issues fall into a handful of buckets. Find your symptom below; each row links to a deeper section if needed.

Troubleshooting matrix

Symptom	Likely cause	First check	Fix
Daemon exits immediately with an auth error	BITPING_API_KEY not set or invalid	echo $BITPING_API_KEY	Re-export the key. Confirm it’s the one from the dashboard, not an old/rotated one.
Stuck on “waiting for peer” forever	Peer filter too strict — no peer matches	Try removing country and lowering min_bandwidth	Loosen the filter, or confirm peer availability on bitping.com.
curl says “Connection refused” on localhost:1080	p2proxy not listening on that port	ss -tlnp | grep 1080	Confirm the daemon is running; check logs with RUST_LOG=debug.
Random failures during long scrapes	Exit peer became unhealthy, failover took a moment	Watch RUST_LOG=debug for peer rotation messages	Confirm peer availability; a pinned peer with no failover entry can’t rotate — add more destination_peers or use fallback_to_discovery.
Hangs behind a corporate firewall	libp2p UDP egress blocked	Try with libp2p UDP egress allowed	Allow UDP egress, or accept relay-only mode (slower).
Docker container immediately dies	TTY mismatch with the TUI	Check container logs	Ensure NO_UI=true is set (it is by default in the official image).
TUI looks garbled	Terminal doesn’t support 24-bit colour	echo $TERM	Use --no-ui, or upgrade your terminal (iTerm2, WezTerm, modern gnome-terminal).
Failed to bind port	Another process already on that port	ss -tlnp | grep <port>	Change the per-server port: in Config.yaml.
Permission denied binding port < 1024	Linux capability needed	—	Bind to a port ≥ 1024, or sudo setcap 'cap_net_bind_service=+ep' $(which p2proxy).
node_keypair.bin errors on startup	Corrupt or missing keypair	ls node_keypair.bin (or your keypair_path)	Delete it — p2proxy regenerates on next start. Note: this changes your peer ID.
/metrics endpoint not responding	Port collision or wrong port	curl http://localhost:9091/metrics	Confirm metrics_port; default is 9091.

Useful debug tactics

Turn the logs up

Logging follows the RUST_LOG env var, which overrides the log_level config key:

RUST_LOG=debug p2proxy --no-ui --config Config.yaml

For really noisy traces, scope by module:

RUST_LOG=p2proxy=trace,libp2p=info p2proxy --config Config.yaml

Verify the SOCKS5 hop

Bypass your application logic and prove the daemon is reachable:

curl -v --socks5-hostname localhost:1080 https://ifconfig.me

If the IP you get back is the peer’s, p2proxy is healthy and the problem is in the calling application.

Watch the metrics

When something’s intermittently broken, the metrics endpoint usually tells the story:

curl -s http://localhost:9091/metrics | grep -E 'p2proxy_(peers_connected|sessions_active|socks_rejected|session_errors)'

A p2proxy_peers_connected value of 0 means peer selection isn’t finding matches — relax your filter.

Still stuck?

Head to Support for escalation paths.