Troubleshooting

Installation Issues

”command not found: epoch-agent”

The agent is not in your PATH. Either:

1. Use the full path:

   ~/.local/bin/epoch-agent --help

2. Add to PATH:

   # For bash
   echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
   source ~/.bashrc
   
   # For zsh
   echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc
   source ~/.zshrc

macOS: “cannot be opened because it is from an unidentified developer”

Remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/epoch-agent

Or allow it in System Settings > Privacy & Security.

Checksum verification failed

The download may be corrupted. Try:

1. Re-download the binary
2. Use a different network
3. Download directly from the releases page

Activation Issues

”Invalid activation code”

• Verify the code is copied correctly (no extra spaces)
• Check if the code has expired (codes expire after 24 hours)
• Generate a new code from the dashboard

”Activation code already used”

Each activation code can only be used once. Generate a new code from your dashboard.

”Connection refused” during activation

Check network connectivity:

# Test API connectivity
curl -v https://api.epochproxy.cloud/health

# Check DNS resolution
nslookup api.epochproxy.cloud

Connection Issues

Agent shows “Offline” in dashboard

1. Check the agent is running:

   # If using systemd
   sudo systemctl status epoch-agent
   
   # If running manually, check process
   ps aux | grep epoch-agent

2. Check network connectivity:

   curl -v https://api.epochproxy.cloud/health

3. Check firewall rules:

   • The agent needs outbound HTTPS (443) access
   • The agent uses WebSocket connections to the relay server

”Connection reset” errors

Usually indicates network issues:

• Check your firewall/proxy settings
• Verify stable internet connection
• The agent will automatically reconnect

Agent keeps reconnecting

Enable debug logging to see what’s happening:

RUST_LOG=epoch_agent=debug epoch-agent

State File Issues

”State file not found”

The agent hasn’t been activated yet. Run with an activation code:

epoch-agent --activation-code YOUR_CODE

“Invalid state file”

The state file may be corrupted. Re-activate:

epoch-agent --force-activate --activation-code YOUR_CODE

State file location

Find where the state file is stored:

• Linux/macOS: ~/.config/epoch-agent/state.json
• Custom: Check --state-file argument or EPOCH_STATE_FILE env var

Service Issues

systemd: Service fails to start

Check logs:

sudo journalctl -u epoch-agent -n 50 --no-pager

Common causes:

• State file permissions
• Binary not found at specified path
• Network not ready at boot

launchd: Service not running

Check status:

launchctl list | grep epochproxy

View logs:

cat ~/Library/Logs/epoch-agent.log

Debug Logging

Enable verbose logging to diagnose issues:

# Debug level
RUST_LOG=epoch_agent=debug epoch-agent

# Trace level (very verbose)
RUST_LOG=epoch_agent=trace epoch-agent

# Log to file
RUST_LOG=epoch_agent=debug epoch-agent 2>&1 | tee agent.log

Getting Help

If you’re still having issues:

1. Check the documentation
2. Enable debug logging and review the output
3. Contact support with:
   • Agent version (epoch-agent --version)
   • Operating system and version
   • Debug log output
   • Steps to reproduce the issue