Drip LogoDrip

Common Errors

Solutions for common issues.

Connection Errors

"failed to connect"

Cause: Cannot reach the server.

Solutions:

  1. Check server address: drip config show
  2. Verify network connectivity: ping tunnel.example.com
  3. Check firewall allows port 443
  4. Ensure server is running: curl https://tunnel.example.com/health

"Invalid authentication token"

Cause: Token doesn't match server configuration.

Solutions:

  1. Verify token: drip config show --full
  2. Re-configure: drip config init
  3. Check server token matches client token
  4. Ensure no extra whitespace in token

"TLS handshake failed"

Cause: TLS version mismatch or certificate issue.

Solutions:

  1. Ensure server uses valid certificate
  2. For self-signed certs (testing only): drip http 3000 --insecure
  3. Check system time is correct
  4. Verify certificate hasn't expired

"connection refused"

Cause: Server not listening on the specified port.

Solutions:

  1. Check server is running: systemctl status drip-server
  2. Verify port is correct
  3. Check firewall rules

Tunnel Errors

"subdomain is already taken"

Cause: Another client is using this subdomain.

Solutions:

  1. Choose a different subdomain
  2. Wait for the other tunnel to disconnect
  3. Use auto-generated subdomain (omit -n)

"subdomain is reserved"

Cause: Using a reserved subdomain name.

Reserved names: www, api, admin, app, mail, ftp, blog, shop, status, health, test, dev, staging

Solution: Choose a different subdomain name.

"invalid subdomain format"

Cause: Subdomain doesn't meet requirements.

Requirements:

  • 3-63 characters
  • Lowercase letters, numbers, hyphens only
  • Cannot start or end with hyphen
  • Pattern: ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$

"tunnel not found"

Cause: Tunnel doesn't exist or was disconnected.

Solutions:

  1. Check tunnel is running: drip list
  2. Restart the tunnel
  3. Verify subdomain spelling

"maximum tunnel limit reached"

Cause: Server has too many active tunnels.

Solutions:

  1. Close unused tunnels
  2. Contact server administrator
  3. Deploy additional server instances

"maximum tunnels per IP reached"

Cause: You've exceeded the per-IP tunnel limit (default: 10).

Solutions:

  1. Close unused tunnels: drip stop all
  2. Wait for existing tunnels to timeout

Server Errors

"TLS certificate path is required"

Cause: Missing --tls-cert flag.

Solution: Provide certificate path:

bash
drip-server --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

"rate limit exceeded"

Cause: Too many tunnel registrations from your IP.

Solution: Wait 1 minute before creating new tunnels.

"permission denied" (certificate files)

Cause: Server user can't read certificate files.

Solution: Grant access:

bash
sudo setfacl -m u:drip:r /etc/letsencrypt/live/tunnel.example.com/*.pem

Debugging

Enable Verbose Logging

bash
drip http 3000 --verbose

Check Configuration

bash
drip config show
drip config validate

View Daemon Logs

bash
drip attach http 3000
# Or directly
cat ~/.drip/daemons/http_3000.log

Check Server Health

bash
curl https://tunnel.example.com/health

Server Logs (Systemd)

bash
sudo journalctl -u drip-server -f

Check Server Stats

bash
curl -H "Authorization: Bearer YOUR_METRICS_TOKEN" https://tunnel.example.com/stats

Network Issues

Tunnel works but is slow

Possible causes:

  • High latency to server
  • Server overloaded
  • Local service slow

Solutions:

  1. Check latency: ping tunnel.example.com
  2. Use a server closer to you
  3. Check local service performance

Tunnel disconnects frequently

Possible causes:

  • Unstable network connection
  • Firewall dropping idle connections
  • Server restarts

Solutions:

  1. Check network stability
  2. Heartbeat keeps connections alive (every 2 seconds)
  3. Client auto-reconnects (up to 5 attempts)

WebSocket connections fail

Cause: Proxy not forwarding upgrade headers.

Solution: Ensure Nginx config includes:

nginx
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
Architecture