Troubleshooting Guide - bgrusnak/flarepipe GitHub Wiki

This comprehensive guide helps you diagnose and fix common FlarePipe issues.

Quick Diagnosis

Start with these quick checks:

# 1. Check if services are running
curl http://localhost:3000    # Your local service
curl https://your-worker.your-subdomain.workers.dev/  # Your tunnel server

# 2. Verify tunnel client
ft --version
ft --host your-worker.your-subdomain.workers.dev --auth your-key --help

# 3. Check network connectivity
ping cloudflare.com
nslookup your-worker.your-subdomain.workers.dev

Common Issues

Connection Issues

"Connection refused" / "ECONNREFUSED"

Symptoms:

Error: connect ECONNREFUSED 127.0.0.1:3000
Failed to start tunnel client: Connection refused

Causes & Solutions:

Local service not running

# Check if service is running
curl http://localhost:3000

# Start your service
npm start
python -m http.server 3000

Wrong port number

# Check which port your service uses
netstat -tlnp | grep :3000
lsof -i :3000

# Update forward rule
ft --host worker.dev --auth key --forward 8080  # Correct port

Service binding to wrong interface

# Service might be binding to 127.0.0.1 only
# Update your service to bind to 0.0.0.0 or localhost

# Or specify the correct local host
ft --host worker.dev --auth key --forward 3000 --local-host 127.0.0.1

"Tunnel server unreachable"

Symptoms:

Failed to connect to tunnel server
HTTP 404 Not Found
Connection timeout

Solutions:

Verify server URL

# Test server directly
curl https://your-worker.your-subdomain.workers.dev/

# Should return 404 (not connection error)

Check deployment status

cd server
wrangler status
npm run tail  # Check logs

Verify DNS resolution

nslookup your-worker.your-subdomain.workers.dev
dig your-worker.your-subdomain.workers.dev

Check firewall/proxy

# Test HTTPS connectivity
curl -v https://cloudflare.com

# Check corporate firewall settings

Authentication Issues

"Authentication failed" / "Unauthorized"

Symptoms:

HTTP 401 Unauthorized
Authentication failed during polling
Invalid auth key

Solutions:

Verify auth key

# Check key length (8-128 characters)
echo -n "your-key" | wc -c

# Check key format (alphanumeric, _, -, . only)
echo "your-key" | grep -E '^[a-zA-Z0-9_.-]+$'

Check server configuration

# Verify server has AUTH_KEY set
wrangler secret list --env production

# Reset if needed
npm run secret:auth

Avoid common mistakes

# ❌ Common mistakes
ft --auth "secret key"      # Space in key
ft --auth secret-key-123!   # Invalid character (!)
ft --auth short             # Too short (<8 chars)

# ✅ Correct format
ft --auth secret-key-123

Tunnel Registration Issues

"Tunnel registration failed"

Symptoms:

Registration failed: 400 Bad Request
Invalid or missing forward_rules
Missing client_info

Solutions:

Check forward rule format

# ❌ Invalid formats
ft --forward api:3000       # Wrong order
ft --forward 3000:api       # Missing leading slash
ft --forward 99999          # Invalid port

# ✅ Valid formats
ft --forward 3000           # Port only (root path)
ft --forward 3000:/api      # Port with path

Verify port availability

# Check if port is in use
netstat -tlnp | grep :3000

# Test port accessibility
curl http://localhost:3000

Request Processing Issues

"Request timeout" / "Gateway Timeout"

Symptoms:

HTTP 504 Gateway Timeout
Request timeout after 30000ms
Failed after 3 attempts

Solutions:

Check local service performance

# Test service response time
time curl http://localhost:3000/api/slow-endpoint

# Monitor service logs for errors

Increase concurrency

# Handle more concurrent requests
ft --host worker.dev --auth key --forward 3000 --concurrency 64

Optimize service

// Add request timeouts to your service
app.use(timeout('25s'));  // Less than tunnel timeout

"Queue is full" / "Worker pool overloaded"

Symptoms:

Tunnel queue is full
Worker pool overloaded - backpressure applied
Too many concurrent requests

Solutions:

Increase client concurrency

ft --host worker.dev --auth key --forward 3000 --concurrency 128

Scale horizontally

# Run multiple client instances
# Terminal 1
ft --host worker.dev --auth key --forward 3000 --concurrency 64

# Terminal 2
ft --host worker.dev --auth key --forward 3001 --concurrency 64

Optimize local services

# Use load balancer for local services
# nginx, HAProxy, or application-level load balancing

Path Routing Issues

"Route not found" / "Path not matching"

Symptoms:

HTTP 404 Not Found
No matching route found
Request not reaching expected service

Solutions:

Check route order

# ❌ Wrong order (generic first)
ft --forward 3000:/ --forward 3001:/api

# ✅ Correct order (specific first)
ft --forward 3001:/api --forward 3000:/

Verify path matching

# Rule: --forward 3000:/api
# Matches: /api, /api/, /api/users, /api/v1/posts
# Doesn't match: /apikey, /api-docs

# Test with curl
curl https://worker.dev/api/test

Debug path routing

# Add debug endpoint to your service
app.get('/debug', (req, res) => {
  res.json({
    path: req.path,
    url: req.url,
    headers: req.headers
  });
});

Performance Issues

"High latency" / "Slow responses"

Symptoms:

Requests taking >5 seconds
Intermittent timeouts
Poor user experience

Diagnostic Steps:

Measure latency components

# Test local service directly
time curl http://localhost:3000/api/test

# Test through tunnel
time curl https://worker.dev/api/test

# Calculate tunnel overhead

Check Cloudflare edge location

# Find nearest edge
curl -H "CF-Ray: trace" https://worker.dev/

# Response headers show edge location

Solutions:

Optimize local service

// Add caching
app.use(express.static('public', { maxAge: '1d' }));

// Use compression
app.use(compression());

// Optimize database queries

Use CDN for static assets

// Serve static files from CDN, not through tunnel
// Only tunnel dynamic API endpoints

Geographic optimization

# Deploy multiple tunnel servers in different regions
# Route users to nearest tunnel

Debugging Tools

Client Debug Mode

Enable verbose logging:

# Enable debug output
DEBUG=flarepipe* ft --host worker.dev --auth key --forward 3000

# Or use verbose flag (if implemented)
ft --host worker.dev --auth key --forward 3000 --verbose

Server Debug Mode

Monitor server logs in real-time:

cd server
npm run tail        # Production logs
npm run tail:dev    # Development logs

Network Debugging

Test network connectivity:

# Test DNS resolution
nslookup your-worker.your-subdomain.workers.dev

# Test HTTPS connectivity  
curl -v https://your-worker.your-subdomain.workers.dev/

# Test with different HTTP methods
curl -X POST -H "Content-Type: application/json" \
  https://your-worker.your-subdomain.workers.dev/api/test

# Check response headers
curl -I https://your-worker.your-subdomain.workers.dev/

Application Debugging

Debug your local service:

# Check service health
curl http://localhost:3000/health

# Monitor service logs
tail -f /var/log/your-service.log

# Check resource usage
top -p $(pgrep node)

Error Codes Reference

HTTP Status Codes

Code	Meaning	Cause	Solution
400	Bad Request	Invalid request format	Check forward rules, auth key format
401	Unauthorized	Auth key mismatch	Verify auth key on client and server
404	Not Found	Route not configured	Check path routing, add catch-all rule
413	Payload Too Large	Request/response too big	Reduce payload size, check limits
429	Too Many Requests	Rate limiting	Reduce request rate, implement backoff
500	Internal Server Error	Server-side error	Check server logs, verify deployment
502	Bad Gateway	Tunnel processing error	Check client connectivity, service health
504	Gateway Timeout	Request timeout	Optimize service, increase timeouts

Client Error Messages

Error	Cause	Solution
"Missing tunnel_id"	Registration failed	Check auth key, server deployment
"Tunnel not found"	Tunnel expired/unregistered	Restart client, check heartbeat
"Invalid rule format"	Malformed forward rule	Use PORT or PORT:PATH format
"Worker pool overloaded"	Too many requests	Increase concurrency, scale horizontally

Advanced Debugging

Packet Capture

Capture network traffic for deep debugging:

# Capture tunnel traffic (macOS/Linux)
sudo tcpdump -i any host your-worker.your-subdomain.workers.dev

# Capture local traffic
sudo tcpdump -i lo port 3000

# Use Wireshark for GUI analysis
wireshark

Memory and Resource Monitoring

Monitor system resources:

# Monitor memory usage
ps aux | grep ft
top -p $(pgrep ft)

# Monitor file descriptors
lsof -p $(pgrep ft)

# Monitor network connections
netstat -an | grep ESTABLISHED

Load Testing

Test tunnel performance under load:

# Install testing tools
npm install -g artillery

# Create load test configuration
cat > load-test.yml << EOF
config:
  target: 'https://your-worker.your-subdomain.workers.dev'
  phases:
    - duration: 60
      arrivalRate: 10
scenarios:
  - name: "API load test"
    requests:
      - get:
          url: "/api/test"
EOF

# Run load test
artillery run load-test.yml

Platform-Specific Issues

Windows Issues

PowerShell Execution Policy

# If scripts are blocked
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Run FlarePipe
ft --host worker.dev --auth key --forward 3000

Windows Firewall

# Allow Node.js through firewall
netsh advfirewall firewall add rule name="Node.js" dir=in action=allow protocol=TCP localport=3000

Path Issues

# Use full paths if needed
"C:\Program Files\nodejs\node.exe" "C:\Users\user\AppData\Roaming\npm\node_modules\flarepipe-client\bin\ft.js"

macOS Issues

Gatekeeper Security

# If app is blocked by Gatekeeper
sudo spctl --master-disable  # Temporary
# Or allow in System Preferences > Security & Privacy

Port Binding Issues

# Check if port is already in use
lsof -i :3000

# Kill process using port
kill -9 $(lsof -t -i:3000)

Linux Issues

Systemd Service

Create a systemd service for automatic startup:

# /etc/systemd/system/flarepipe.service
[Unit]
Description=FlarePipe Tunnel Client
After=network.target

[Service]
Type=simple
User=tunnel
ExecStart=/usr/bin/ft --config /etc/flarepipe/tunnel.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable flarepipe.service
sudo systemctl start flarepipe.service
sudo systemctl status flarepipe.service

SELinux Issues

# Check SELinux status
sestatus

# If blocking connections
sudo setsebool -P httpd_can_network_connect 1

# Or create custom policy
sudo ausearch -m avc -ts recent | grep ft

Docker and Container Issues

Container Networking

# Check container network
docker network ls
docker inspect bridge

# Test connectivity from container
docker run --rm -it alpine/curl curl http://host.docker.internal:3000

Docker Compose Setup

# docker-compose.yml
version: '3.8'
services:
  app:
    image: node:18
    ports:
      - "3000:3000"
    volumes:
      - .:/app
    working_dir: /app
    command: npm start

  tunnel:
    image: node:18
    depends_on:
      - app
    environment:
      - FLAREPIPE_HOST=worker.dev
      - FLAREPIPE_AUTH=your-key
    command: |
      sh -c "
        npm install -g flarepipe-client &&
        ft --host $FLAREPIPE_HOST --auth $FLAREPIPE_AUTH --forward app:3000
      "

Kubernetes Issues

# kubernetes-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: flarepipe-tunnel
spec:
  replicas: 1
  selector:
    matchLabels:
      app: flarepipe-tunnel
  template:
    metadata:
      labels:
        app: flarepipe-tunnel
    spec:
      containers:
      - name: tunnel
        image: node:18
        env:
        - name: FLAREPIPE_HOST
          valueFrom:
            secretKeyRef:
              name: flarepipe-secret
              key: host
        - name: FLAREPIPE_AUTH
          valueFrom:
            secretKeyRef:
              name: flarepipe-secret
              key: auth
        command:
        - sh
        - -c
        - |
          npm install -g flarepipe-client
          ft --host $FLAREPIPE_HOST --auth $FLAREPIPE_AUTH --forward app-service:3000

CI/CD Integration Issues

GitHub Actions

# .github/workflows/tunnel.yml
name: Deploy with Tunnel
on: [push]

jobs:
  test-with-tunnel:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: 18
    
    - name: Start application
      run: |
        npm install
        npm start &
        sleep 10
    
    - name: Start tunnel
      env:
        FLAREPIPE_HOST: ${{ secrets.FLAREPIPE_HOST }}
        FLAREPIPE_AUTH: ${{ secrets.FLAREPIPE_AUTH }}
      run: |
        npm install -g flarepipe-client
        ft --host $FLAREPIPE_HOST --auth $FLAREPIPE_AUTH --forward 3000 &
        sleep 10
    
    - name: Run tests
      run: |
        curl $FLAREPIPE_HOST/api/health
        npm test

GitLab CI

# .gitlab-ci.yml
stages:
  - test

test-with-tunnel:
  stage: test
  image: node:18
  services:
    - name: your-app:latest
      alias: app
  variables:
    FLAREPIPE_HOST: $TUNNEL_HOST
    FLAREPIPE_AUTH: $TUNNEL_AUTH
  script:
    - npm install -g flarepipe-client
    - ft --host $FLAREPIPE_HOST --auth $FLAREPIPE_AUTH --forward app:3000 &
    - sleep 10
    - curl $FLAREPIPE_HOST/api/health
    - npm test

Monitoring and Alerting

Health Check Script

#!/bin/bash
# health-check.sh

TUNNEL_URL="https://your-worker.your-subdomain.workers.dev"
LOCAL_URL="http://localhost:3000"

# Check local service
if ! curl -f $LOCAL_URL/health > /dev/null 2>&1; then
    echo "Local service is down"
    exit 1
fi

# Check tunnel
if ! curl -f $TUNNEL_URL/health > /dev/null 2>&1; then
    echo "Tunnel is down"
    exit 1
fi

echo "All services healthy"

Nagios/Icinga Check

#!/bin/bash
# check_flarepipe.sh

STATE_OK=0
STATE_WARNING=1
STATE_CRITICAL=2
STATE_UNKNOWN=3

TUNNEL_URL=$1
EXPECTED_CODE=${2:-200}

if [ -z "$TUNNEL_URL" ]; then
    echo "UNKNOWN - Missing tunnel URL"
    exit $STATE_UNKNOWN
fi

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" "$TUNNEL_URL")

if [ "$RESPONSE" = "$EXPECTED_CODE" ]; then
    echo "OK - Tunnel responding with $RESPONSE"
    exit $STATE_OK
else
    echo "CRITICAL - Tunnel responding with $RESPONSE, expected $EXPECTED_CODE"
    exit $STATE_CRITICAL
fi

Prometheus Metrics

// Add to your application
const client = require('prom-client');

const tunnelRequests = new client.Counter({
  name: 'flarepipe_requests_total',
  help: 'Total requests through FlarePipe tunnel',
  labelNames: ['method', 'status']
});

app.use((req, res, next) => {
  res.on('finish', () => {
    tunnelRequests.labels(req.method, res.statusCode).inc();
  });
  next();
});

Recovery Procedures

Automatic Recovery

#!/bin/bash
# auto-recovery.sh

TUNNEL_URL="https://your-worker.your-subdomain.workers.dev"
CONFIG_FILE="/etc/flarepipe/tunnel.yaml"

while true; do
    if ! curl -f $TUNNEL_URL/health > /dev/null 2>&1; then
        echo "$(date): Tunnel down, restarting..."
        
        # Kill existing tunnel
        pkill -f "ft --config"
        
        # Wait a moment
        sleep 5
        
        # Restart tunnel
        ft --config $CONFIG_FILE &
        
        # Wait before next check
        sleep 30
    fi
    
    sleep 60
done

Manual Recovery Steps

Identify the problem

# Check what's running
ps aux | grep ft

# Check logs
journalctl -u flarepipe.service -f

Stop everything cleanly

# Stop tunnel client
pkill -f ft

# Stop local services
sudo systemctl stop your-app

Restart in order

# Start local services first
sudo systemctl start your-app

# Verify local service
curl http://localhost:3000/health

# Start tunnel
ft --config tunnel.yaml

Verify recovery

# Test end-to-end
curl https://your-worker.your-subdomain.workers.dev/health

Getting Help

Information to Collect

When reporting issues, include:

# System information
uname -a
node --version
npm --version

# FlarePipe version
ft --version

# Configuration (remove sensitive data)
cat tunnel.yaml

# Recent logs
journalctl -u flarepipe.service --since "1 hour ago"

# Network connectivity
curl -v https://your-worker.your-subdomain.workers.dev/

Support Channels

GitHub Issues
- Report bugs
- Search existing issues first
- Use issue templates
Community Discord
- Real-time help from community
- Share configuration files (sanitized)
- Get quick answers
Stack Overflow
- Tag questions with flarepipe
- Include complete error messages
- Provide minimal reproducible examples
Documentation
- Wiki
- FAQ
- Examples

Creating Good Bug Reports

# Bug Report Template

## Expected Behavior
What should happen

## Actual Behavior  
What actually happens

## Steps to Reproduce
1. Step one
2. Step two
3. Error occurs

## Environment
- OS: Ubuntu 20.04
- Node.js: v18.17.0
- FlarePipe: v1.0.0

## Configuration
```yaml
# Your tunnel.yaml (remove auth key)
host: worker.dev
forward:
  - 3000:/api

Logs

Error messages here

Additional Context

Any other relevant information


---

**Still having issues?** Don't hesitate to reach out to the community. Most problems have been solved before, and the community is happy to help!

**Next Steps:**
- Check [Common Issues](common-issues) for known problems
- Review [Performance Guide](performance) for optimization
- Set up [Monitoring](monitoring) to prevent future issues