Troubleshooting

This guide covers common issues with RelayCore, grouped by category with diagnostic steps and solutions.

Certificate & TLS

Browser shows untrusted certificate

  • Cause: RelayCore generates a self-signed CA, not trusted by the system
  • Fix: Generate and install the CA 
    relay-core-cli ca generate
relay-core-cli ca install   # macOS

# Or manually (example)
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.relay-core/ca_cert.pem

curl reports SSL errors

  • Temporarily skip: curl --cacert ~/.relay-core/ca_cert.pem https://example.com
  • Environment variable: export CURL_CA_BUNDLE=~/.relay-core/ca_cert.pem

Connection Issues

Proxy fails to start (port in use)

  • Check port: lsof -i :8080 or netstat -an | grep 8080
  • Change port: relay-core-cli run --listen 127.0.0.1:9090

Client connects but gets no response

  • Verify proxy address and port are correct
  • Check system proxy settings
  • Check for security software blocking the connection
  • Enable verbose logging: RUST_LOG=info relay-core-cli run

Upstream request timeout

  • Increase timeout: --request-timeout-ms 30000
  • Check upstream: curl -v http://upstream-host/path
  • Check the error field in Flow details

Rule Engine

Rule not firing

  • Check "active": true
  • Verify stage matches the traffic stage
  • Verify filter mode — Contains is case-sensitive
  • Check if a higher-priority rule with Stop terminated processing
  • Check matched rules via script: console.log(flow.matched_rules)

RateLimit not working as expected

  • Ensure window_ms is large enough (minimum 1000ms)
  • Verify Mustache variables in key are correct ({{ip}} not {{clientip}})
  • RateLimit does not auto-reject — combine with a script or follow-up rule

WebSocket

WebSocket disconnects immediately

  • Check if onConnect hook returns {drop: true}
  • Check for Drop action in Connect stage rules

WebSocket messages not appearing

  • Ensure TUI or frontend is on the correct WS tab
  • Check if DropWebSocketMessage action is discarding messages

Transparent Proxy

Transparent proxy not intercepting (macOS)

  • Verify PF rules are loaded: sudo pfctl -s nat
  • Ensure RelayCore runs as root
  • macOS PF UDP transparent proxy is currently experimental

Transparent proxy not intercepting (Linux)

  • Verify iptables TPROXY rules are correct
  • Ensure SO_ORIGINAL_DST is available
  • Check /proc/sys/net/ipv4/conf/*/route_localnet

Performance

Requests are slow through the proxy

  • Audit rule count — every rule evaluates on every matching flow
  • Check ResponseBody filters — they cache the full body
  • Check script execution time via script_hook_duration_us metric
  • Reduce log level: RUST_LOG=warn relay-core-cli run

Memory grows continuously

  • Check Flow memory limit (default 10000)
  • Check that sharedState entries are cleaned up (warning at 10k keys)
  • Check WebSocket message buffer limit (default 2000)

Logging & Debugging

# Full debug logging
RUST_LOG=debug relay-core-cli run

# Script-only logging
RUST_LOG=relay_core_script=debug relay-core-cli run

# View live flow events
curl -N http://127.0.0.1:8082/api/v1/events

# View metrics
curl http://127.0.0.1:8082/api/v1/metrics
curl http://127.0.0.1:8082/api/v1/metrics/prometheus

Getting Help