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 at log_level: debug.
First request slow, subsequent ones fast	Cold connection pool	Look at p2proxy_stream_pool_size{state="idle"}	Increase min_idle so warm streams are always ready.
Random failures during long scrapes	Per-peer error rate exceeded max_error_rate, rotation took a moment	Watch log_level: debug for “rotating peer” messages	Lower max_error_rate for faster failover; bump max_retries.
Hangs behind a corporate firewall	UDP/45445 blocked egress	Try with the libp2p port open in egress firewall	Open the port, 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 ~/.config/p2proxy/node_keypair.bin	Delete it — p2proxy regenerates on next start. Note: this changes your peer ID.
/metrics endpoint not responding	Metrics disabled or port collision	curl http://localhost:9091/metrics	Confirm metrics port; default is 9091.

Useful debug tactics

Turn the logs up

Set log_level: debug in Config.yaml, or use RUST_LOG:

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_(socks5_requests|stream_pool|peer_connections)'

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

Still stuck?

Head to Support for escalation paths.