Troubleshooting

Quick solutions to common problems you might encounter while using Private Connect.

Connection Issues

Agent won't connect to Hub

Symptoms:

connect up hangs or times out
Error: “Failed to connect to Hub”
WebSocket connection errors

Solutions:

Check Hub URL

# Verify you're using the correct Hub URL
connect up --hub https://api.privateconnect.co

# Or set environment variable
export CONNECT_HUB_URL=https://api.privateconnect.co
connect up

Check network connectivity

# Test if Hub is reachable
curl https://api.privateconnect.co/health

# Should return: {"status":"ok"}

Check firewall/proxy settings
- Ensure outbound HTTPS (443) is allowed
- WebSocket connections must be permitted
- Corporate proxies may block WebSocket traffic

Try with verbose logging

connect up --verbose
# Check logs for specific error messages

Check for expired token

# Rotate token if expired
connect up --rotate-token

Service not found

Symptoms:

Error: “Service ‘prod-db’ not found”
connect reach fails to find service

Solutions:

List available services

connect ls
# Shows all services in your workspace

Check service name

# Service names are case-sensitive
connect reach prod-db     # ✓ Correct
connect reach Prod-DB     # ❌ Wrong case

Verify workspace

# Ensure you're in the same workspace as the service
connect status
# Check "Workspace" field

Check if exposing agent is online

# The agent exposing the service must be running
connect ls --verbose
# Shows which agent is exposing each service

Re-expose the service

# On the machine with the service
connect expose localhost:5432 --name prod-db

Port already in use

Symptoms:

Error: “Port 5432 is already in use”
connect reach fails to create tunnel

Solutions:

Use a different local port

connect reach prod-db --port 5433
# Access at localhost:5433 instead

Find what’s using the port

# On macOS/Linux
lsof -i :5432

# On Windows
netstat -ano | findstr :5432

Stop the conflicting service

# Example: stop local PostgreSQL
brew services stop postgresql
# or
sudo systemctl stop postgresql

Clear port mapping

# Remove saved port mapping
connect map --clear prod-db
# Next connection will try a different port

Connection keeps dropping

Symptoms:

Tunnel disconnects frequently
“Connection reset by peer” errors
Intermittent connectivity

Solutions:

Check network stability

# Test latency and packet loss
ping -c 10 api.privateconnect.co

Use daemon mode for persistence

# Install as system service
connect daemon install

# Daemon auto-reconnects on disconnect

Check for token expiry

connect status
# Look for "Token expires in" warning

# Rotate if expiring soon
connect up --rotate-token

Increase timeout settings

# Set longer timeouts (self-hosted only)
export CONNECT_TIMEOUT=60000  # 60 seconds
connect up

Check Hub status

# For hosted version, check status page
curl https://api.privateconnect.co/health

Authentication Issues

Symptoms:

Browser doesn’t open for login
Magic link email not received
Error: “Authentication failed”

Solutions:

Use device code flow

# For headless servers
connect up --device
# Enter code from any device at the provided URL

Check email spam folder
- Magic link emails may be filtered
- Add [email protected] to contacts

Try different browser

# Specify browser
BROWSER=firefox connect up

Use API key instead

# Generate API key from web UI
connect up --api-key pc_xxxxxxxxxxxxx

Clear saved credentials

# Remove old auth data
rm -rf ~/.connect/auth.json
connect up

Token expired

Symptoms:

Error: “Token has expired”
Agent won’t authenticate
401 Unauthorized errors

Solutions:

Rotate token

connect up --rotate-token
# Generates new token, invalidates old one

Log in again

# Re-authenticate from scratch
rm -rf ~/.connect/auth.json
connect up

Set up token rotation reminders

# Check token status regularly
connect status
# Shows "Token expires in X days"

Permission denied

Symptoms:

Error: “Permission denied”
Cannot expose services
Cannot create shares

Solutions:

Check workspace membership

connect status
# Verify you're in the correct workspace

Use API key with correct permissions

# API keys inherit workspace permissions
# Generate new key from web UI if needed

Contact workspace admin
- Only workspace members can expose services
- Admin can invite you from the web UI

Service Exposure Issues

Cannot expose service

Symptoms:

connect expose fails
Service not appearing in connect ls
Error: “Failed to expose service”

Solutions:

Verify target is reachable

# Test if service is listening
nc -zv localhost 5432
# Or
telnet localhost 5432

Check service is actually running

# Example: PostgreSQL
pg_isready -h localhost -p 5432

# Example: Redis
redis-cli -p 6379 ping

Use explicit name

# Sometimes auto-naming fails
connect expose localhost:5432 --name my-db

Check for duplicate names

# List existing services
connect ls

# Delete old service if needed
connect delete old-service

Verify agent is connected

connect status
# Should show "Connected: yes"

Service shows offline

Symptoms:

Service listed but marked as offline
Cannot reach service
Health check fails

Solutions:

Check exposing agent

# Agent must be running on the machine with the service
connect status  # On the exposing machine

Restart agent

# If using daemon
connect daemon restart

# If running manually
# Stop (Ctrl+C) and restart
connect up

Re-expose service

connect expose localhost:5432 --name prod-db

Check target service health

# Ensure the actual service is running
systemctl status postgresql  # Example

Public URL not working

Symptoms:

connect expose --public creates URL but it doesn’t work
502 Bad Gateway errors
URL times out

Solutions:

Verify service is exposed

connect ls
# Should show your service with public URL

Check if agent is running

# Agent must stay running for public URLs
connect status

Test local access first

# Ensure service works locally
curl http://localhost:3000

Check service bindings

# Service must bind to 127.0.0.1 or 0.0.0.0
# NOT just localhost (IPv6)
netstat -tuln | grep 3000

Try temporary tunnel

# For quick testing without auth
npx private-connect tunnel 3000

Share code not working

Symptoms:

connect join fails with invalid code
Error: “Share not found”
Share code expired

Solutions:

Check code validity

# Codes are case-sensitive
connect join x7k9m2    # ✓ Correct
connect join X7K9M2    # ❌ Wrong case

Verify expiration

# Shares can expire
# Creator should check from web UI or:
connect share --list

Create new share

# If expired, create new one
connect share --expires 7d

Check workspace access
- Both parties must have access to workspace
- Or use connect link for external access

Cannot clone teammate environment

Symptoms:

connect clone shows no teammates
Error: “No teammates found”
Clone succeeds but no services appear

Solutions:

List available teammates

connect clone --list
# Shows agents in your workspace

Ensure teammate has exposed services

# Teammate must have services exposed
# Ask them to run: connect ls

Use share code instead

# More reliable for collaboration
# Creator: connect share
# You: connect join <code>

Verify same workspace

connect status
# Both must be in same workspace

Public link access denied

Symptoms:

403 Forbidden on public link
Rate limit exceeded
Method not allowed

Solutions:

Check allowed methods

# Link may restrict HTTP methods
# If link allows only GET, POST won't work

Check allowed paths

# Link may restrict paths
# /api/admin may be blocked
# /api/public may be allowed

Check rate limit

# Wait a minute if rate limited
# Or creator can increase limit:
connect link api --rate-limit 200

Verify link not revoked
- Creator may have revoked access
- Check web UI for active links

Debug Mode Issues

No packets showing in debug viewer

Symptoms:

Debug viewer shows no traffic
Packets not being captured
Empty packet list

Solutions:

Verify debug mode is enabled

# Must use --debug flag
connect expose localhost:3000 --debug

Check traffic is flowing

# Send test request
curl http://localhost:3000
# Should appear in debug viewer

Refresh debug viewer
- Refresh browser page
- Check WebSocket connection status
Check browser console
- Open DevTools → Console
- Look for WebSocket errors

Verify session is active

# Agent must be running
# Debug session ends when agent stops
connect status

AI not working in debug viewer

Symptoms:

AI copilot not responding
Error: “AI not configured”
API errors

Solutions:

Configure AI provider
- Go to Settings → AI Copilot in web UI
- Choose provider (Ollama, OpenAI, Anthropic)
- Enter API key
- Click “Test Connection”
Check API credits
- For OpenAI/Anthropic, verify you have API credits
- Check provider dashboard

Verify Ollama is running

# For local Ollama
ollama serve
# In another terminal:
ollama pull llama2  # or your preferred model

Try different provider
- If one provider fails, try another
- Ollama is best for privacy-sensitive data

Debug session expired

Symptoms:

Error: “Session expired”
Cannot view debug history
Old sessions not accessible

Solutions:

Restart debug session

# Debug sessions are tied to agent lifecycle
connect expose localhost:3000 --debug

Export before stopping
- Export session as JSON or Markdown before stopping agent
- Use “Export” button in debug viewer

Keep agent running

# Use daemon mode for persistent sessions
connect daemon install
connect expose localhost:3000 --debug

Installation Issues

Install script fails

Symptoms:

curl -fsSL ... | bash fails
Permission denied errors
Binary not found after install

Solutions:

Check system requirements
- macOS 10.15+, Linux (x64/arm64), Windows (WSL)
- curl must be installed

Manual installation

# Download binary directly
curl -Lo connect https://privateconnect.co/download/latest/linux-x64
chmod +x connect
sudo mv connect /usr/local/bin/

Use package managers

# Homebrew (macOS)
brew install treadiehq/tap/private-connect

# Coming soon: apt, yum, scoop

Build from source

git clone https://github.com/treadiehq/private-connect.git
cd private-connect
pnpm install
cd apps/agent && pnpm run build:binary

Binary won't run

Symptoms:

“Permission denied” when running connect
“Command not found: connect”
Binary fails to execute

Solutions:

Make executable
```
chmod +x /usr/local/bin/connect
```

Check PATH

# Ensure /usr/local/bin is in PATH
echo $PATH | grep /usr/local/bin

# Add to PATH if missing
export PATH="/usr/local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc

Try absolute path
```
/usr/local/bin/connect up
```

Check architecture

# Verify binary matches your system
uname -m    # x86_64 or arm64
file /usr/local/bin/connect

Daemon installation fails

Symptoms:

connect daemon install fails
Systemd/launchd errors
Service won’t start on boot

Solutions:

Check permissions

# May need sudo for system-wide install
sudo connect daemon install

Verify init system

# Linux: check if systemd is available
systemctl --version

# macOS: launchd is default
launchctl version

Check logs

# Linux (systemd)
sudo journalctl -u private-connect

# macOS (launchd)
tail -f ~/Library/Logs/private-connect.log

Manual service file

# Create systemd service manually
sudo nano /etc/systemd/system/private-connect.service
# Add service configuration
sudo systemctl daemon-reload
sudo systemctl enable private-connect
sudo systemctl start private-connect

Performance Issues

Slow connection speeds

Symptoms:

High latency through tunnel
Slow database queries
Timeouts on large transfers

Solutions:

Check network latency

# Test latency to Hub
ping api.privateconnect.co

# Test connection speed
connect reach prod-db --check
# Shows latency measurement

Use regional Hub (self-hosted)

# Deploy Hub closer to your agents
connect up --hub https://eu.yourdomain.com

Disable debug mode

# Debug adds ~1-2ms overhead per request
# Don't use --debug in production
connect expose localhost:3000  # Without --debug

Check for network issues

# Test for packet loss
ping -c 100 api.privateconnect.co
# Should be 0% packet loss

High CPU/memory usage

Symptoms:

Agent using excessive resources
System slowdown
Memory leaks

Solutions:

Check version

connect version
# Update to latest version
curl -fsSL https://privateconnect.co/install.sh | bash

Reduce concurrent connections

# Limit number of active tunnels
# Close unused connections
connect ls
connect disconnect <service>

Monitor resource usage

# Check agent process
ps aux | grep connect
top -p $(pgrep connect)

Restart agent

# If using daemon
connect daemon restart

Getting Help

If you’re still experiencing issues:

Documentation

Read the full documentation

Discord Community

Ask questions in Discord

GitHub Issues

Report bugs or request features

Provide Debug Information

When asking for help, include:

# System info
connect version
uname -a

# Connection status
connect status

# Service list
connect ls

# Recent logs (if applicable)
connect daemon logs

Common Error Messages

Error	Meaning	Solution
`Service not found`	Service doesn’t exist or wrong workspace	Check `connect ls`, verify workspace
`Port already in use`	Local port is occupied	Use `--port` flag or stop conflicting service
`Token expired`	Agent token needs rotation	Run `connect up --rotate-token`
`Permission denied`	Not authorized for action	Check workspace membership, use API key
`Connection refused`	Cannot reach target service	Verify service is running locally
`WebSocket error`	Cannot connect to Hub	Check network, firewall, Hub status
`Authentication failed`	Login issue	Use `--device` flag or API key
`Share not found`	Invalid or expired share code	Get new share code from creator
`Rate limit exceeded`	Too many requests to public link	Wait or contact link creator to increase limit
`Hub unreachable`	Network or Hub issue	Check `curl https://api.privateconnect.co/health`

Learn

Self-Hosting

Connection Issues

Authentication Issues

Service Exposure Issues

Debug Mode Issues

Installation Issues

Performance Issues

Getting Help

Documentation

Discord Community

GitHub Issues

Provide Debug Information

Common Error Messages

Build docs developers (and LLMs) love

Learn

Self-Hosting

​Connection Issues

​Authentication Issues

​Service Exposure Issues

​Sharing & Collaboration Issues

​Debug Mode Issues

​Installation Issues

​Performance Issues

​Getting Help

Documentation

Discord Community

GitHub Issues

​Provide Debug Information

​Common Error Messages

Build docs developers (and LLMs) love

Connection Issues

Authentication Issues

Service Exposure Issues

Sharing & Collaboration Issues

Debug Mode Issues

Installation Issues

Performance Issues

Getting Help

Provide Debug Information

Common Error Messages