Diagnostic Command Start troubleshooting by running the built-in diagnostic:
Example output: OS: linux x64 (supported) API (https://api.example.com): reachable Auth session: present ([email protected] ) cloudflared: found at /home/user/.rs-tunnel/bin/cloudflared (2024.12.0)
This checks:
Operating system compatibility
API server connectivity
Authentication session status
Cloudflared binary installation
Run rs-tunnel doctor before reporting issues. It often reveals the problem immediately.
Common Issues Cannot Find Module ‘@ripeseed/shared’ Error: Error: Cannot find module '@ripeseed/shared'
Cause: The shared package dependency is missing or not built.Solutions:
Reinstall rs-tunnel
npm uninstall -g @ripeseed/rs-tunnel npm install -g @ripeseed/rs-tunnel
Clear npm cache (if reinstall fails)
npm cache clean --force npm install -g @ripeseed/rs-tunnel
This typically occurs when the package was published before @ripeseed/shared was available in the registry.
EPERM: Operation Not Permitted Error: Cause: Insufficient permissions to bind to a local port for the reverse proxy.Solutions: Check Port Availability Another process may be using the port: # Linux/macOS lsof -i :3000 # Windows netstat -ano | findstr :3000
Run as Normal User rs-tunnel doesn’t require root/admin privileges. If running as root, switch to a normal user account.
API Connection Failed Error: API (https://api.example.com): unreachable
Cause: Cannot connect to the configured API server.Solutions:
Verify API URL
Check your configuration: # Check environment variable echo $RS_TUNNEL_API_URL # Check config file cat ~/.rs-tunnel/config.json
Test API Directly
curl https://api.example.com/healthz
Should return HTTP 200 if the API is healthy. Ensure your API URL includes the protocol (https://) and has no trailing slash.
Slack OAuth Callback Fails Error: OAuth state mismatch. Aborting login.
Cause: The OAuth state parameter doesn’t match, often due to:
Mismatched redirect URI in Slack app configuration
Browser cache/cookie issues
System clock skew
Solutions:
Verify Redirect URI
The SLACK_REDIRECT_URI in your API server must exactly match the redirect URI in your Slack app settings. Example: https://api.example.com/v1/auth/slack/callback
Clear Browser Data
Clear cookies and cache for the rs-tunnel domain, then retry:
Check System Clock
Ensure your system clock is synchronized: # Linux/macOS date # Sync if needed (Linux) sudo ntpdate -s time.nist.gov
Access Denied During Login Error: Failed to authenticate (status=403, code=FORBIDDEN_EMAIL_DOMAIN )
or
Failed to authenticate (status=403, code=FORBIDDEN_SLACK_TEAM )
Cause: Your email domain or Slack workspace is not authorized.Solutions: Only users with email addresses matching ALLOWED_EMAIL_DOMAIN and belonging to the authorized Slack workspace (ALLOWED_SLACK_TEAM_ID) can authenticate.
Verify your email domain matches the server’s ALLOWED_EMAIL_DOMAINConfirm Slack workspace membershipContact your administrator to verify server configuration
Tunnel Creation Quota Exceeded Error: Failed to create tunnel (status=429, code=QUOTA_EXCEEDED )
Cause: You’ve reached the maximum number of active tunnels (default: 5).Solution: Stop unused tunnels to free up quota:
rs-tunnel list rs-tunnel stop < tunnel-id-or-hostnam e >
Keep your active tunnel count low by stopping tunnels when you’re done with them.
Cloudflared Not Found Error: Cause: The CLI couldn’t download or find the cloudflared binary.Solutions:
Check Download Permissions
Ensure ~/.rs-tunnel/bin/ is writable: ls -la ~/.rs-tunnel/ mkdir -p ~/.rs-tunnel/bin chmod 700 ~/.rs-tunnel/bin
Manual Installation
Download cloudflared manually: # Linux curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ~/.rs-tunnel/bin/cloudflared chmod +x ~/.rs-tunnel/bin/cloudflared # macOS curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-amd64 -o ~/.rs-tunnel/bin/cloudflared chmod +x ~/.rs-tunnel/bin/cloudflared
Tunnel Connection Issues Symptoms:
Tunnel creates successfully but requests time out
Dashboard shows “0 requests”
Public URL returns 502 Bad Gateway
Solutions:
Verify Local Service
Ensure your local service is actually running: curl http://localhost:3000
Check Firewall
Ensure cloudflared can connect to Cloudflare’s edge:
Allow outbound HTTPS (443)
Allow outbound HTTP (80)
Use Verbose Mode
Run with --verbose to see cloudflared logs: rs-tunnel up --port 3000 --verbose
Look for connection errors or region information. Token Expired Error: Failed to create tunnel (status=401, code=UNAUTHORIZED )
Cause: Your refresh token has expired (default: 30 days).Solution: Log in again:
Access tokens (15 minutes) are automatically refreshed by the CLI. You only need to re-login when your refresh token expires.
DNS Record Already Exists Error: Failed to create tunnel (status=409, code=SLUG_CONFLICT )
Cause: The requested slug is already in use by another tunnel.Solutions: Use Different Slug rs-tunnel up --port 3000 --url my-app-v2
Stop Existing Tunnel rs-tunnel list rs-tunnel stop my-app.tunnel.example.com rs-tunnel up --port 3000 --url my-app
Database Migration Errors These errors occur during API server setup, not CLI usage. Included here for completeness.
Error during API migration: Can 't find meta/_journal.json
Cause: Drizzle migration metadata is missing.Solution: Ensure apps/api/drizzle/meta/_journal.json exists in the API server repository.
Client Password Must Be a String Error during API startup: client password must be a string
Cause: DATABASE_URL environment variable is missing or incomplete.Solution: Verify API server configuration:
# In API server environment echo $DATABASE_URL # Should output: postgresql://user:password@host:5432/database
Getting Help If you’ve tried the solutions above and still have issues:
GitHub Issues Report bugs and request features
Provide Diagnostics Include output from: rs-tunnel doctor rs-tunnel --version node --version
Do not share sensitive information like access tokens, refresh tokens, or your Cloudflare API credentials when reporting issues.
Debug Mode For verbose debugging, use the --verbose flag with up:
rs-tunnel up --port 3000 --verbose
This shows:
Raw cloudflared connection logs
Region and datacenter information
Connection establishment details
Copy and save verbose output when reporting connection issues to GitHub.
Next Steps
Configuration Review configuration options and API domain setup
