🔧 Cloudflare Tunnel Troubleshooting Guide

Step-by-step solutions for common tunnel setup failures and configuration issues

🚨 Troubleshooting ⏱️ 20 minutes 📊 Intermediate 🔥 Based on Real Issues

Most Common Issues

1

Diagnose the Current Problem

Before fixing anything, identify exactly what's failing. Check service status, logs, and current configuration.

# Check tunnel service status sudo systemctl status cloudflared # View recent error logs sudo journalctl -u cloudflared -n 50 # Check if DNS record exists nslookup your-domain.com dig your-domain.com # Test local service curl -I http://localhost:80
⚠️
Common Error Messages
Look for: "Tunnel credentials file doesn't exist", "Cannot determine default origin certificate", "Failed to start", or "Access through untrusted domain"
2

Perform Complete Clean Reset

When troubleshooting fails, start fresh. This removes all existing tunnel configurations and service files.

# Stop and disable current service sudo systemctl stop cloudflared sudo systemctl disable cloudflared # Remove systemd service file sudo rm -f /etc/systemd/system/cloudflared.service sudo systemctl daemon-reload # Clean up all config files sudo rm -rf /etc/cloudflared/ rm -rf ~/.cloudflared/ # Optional: Remove cloudflared binary for fresh install sudo rm -f /usr/local/bin/cloudflared
🗑️
Complete Reset Warning
This removes ALL tunnel configurations. You'll need to delete the old tunnel in Cloudflare dashboard and create a new one.
3

Create Fresh Tunnel

Re-authenticate with Cloudflare and create a new tunnel with proper credentials handling.

# Re-authenticate with Cloudflare cloudflared tunnel login # Create new tunnel with descriptive name cloudflared tunnel create your-project-name # Note the tunnel ID from output # Example: Created tunnel your-project-name with id 86e1a942-f0f6-47aa-954d-8011f027dd47
✅
Success Indicators
You should see "Created tunnel [name] with id [uuid]" and credentials file created in ~/.cloudflared/
4

Configure Tunnel Properly

Set up the configuration file and copy credentials to the correct system location with proper permissions.

# Create system config directory sudo mkdir -p /etc/cloudflared # Create configuration file (replace TUNNEL_ID with your actual ID) sudo tee /etc/cloudflared/config.yml > /dev/null << 'EOF' tunnel: YOUR_TUNNEL_ID credentials-file: /etc/cloudflared/YOUR_TUNNEL_ID.json ingress: - hostname: your-domain.com service: http://localhost:80 - service: http_status:404 EOF # Copy credentials file to system location sudo cp ~/.cloudflared/YOUR_TUNNEL_ID.json /etc/cloudflared/ sudo chown root:root /etc/cloudflared/YOUR_TUNNEL_ID.json sudo chmod 600 /etc/cloudflared/YOUR_TUNNEL_ID.json
💡
Configuration Tips
Replace YOUR_TUNNEL_ID with the actual tunnel ID from step 3. Make sure your-domain.com matches your actual domain.
5

Test Configuration Manually

Always test the tunnel manually before creating the systemd service to catch configuration errors early.

# Test tunnel configuration manually sudo cloudflared tunnel --config /etc/cloudflared/config.yml run # You should see: # - "Starting tunnel tunnelID=YOUR_TUNNEL_ID" # - "Registered tunnel connection" messages # - No error messages about missing files # Press Ctrl+C to stop the manual test
🎯
Success Indicators
Look for "Registered tunnel connection" entries with different connection IDs and IP addresses.
6

Create Reliable System Service

Create a robust systemd service that will start automatically and restart on failure.

# Create systemd service file sudo tee /etc/systemd/system/cloudflared.service > /dev/null << 'EOF' [Unit] Description=cloudflared After=network.target [Service] TimeoutStartSec=0 Type=notify ExecStart=/usr/local/bin/cloudflared tunnel --config /etc/cloudflared/config.yml run Restart=always RestartSec=5s [Install] WantedBy=multi-user.target EOF # Enable and start service sudo systemctl daemon-reload sudo systemctl enable cloudflared sudo systemctl start cloudflared # Verify service is running sudo systemctl status cloudflared
⚙️
Service Configuration
The service includes automatic restart and proper timing to handle network connectivity issues.
7

Update DNS Records

The most critical step - ensure DNS points to your NEW tunnel ID, not an old one.

# In Cloudflare Dashboard: # 1. Go to DNS → Records # 2. Find your domain's CNAME record # 3. Update the target to: YOUR_TUNNEL_ID.cfargotunnel.com # 4. Ensure Proxy status is "Proxied" (orange cloud) # Verify DNS propagation nslookup your-domain.com dig your-domain.com CNAME # Test the connection curl -I https://your-domain.com
🌐
DNS Update Critical
This is the most common failure point. Old DNS records pointing to deleted tunnels cause 404 errors.
8

Configure Application Trusted Domains

Many applications need to be configured to accept requests from your new domain.

# For Nextcloud - add to trusted_domains in config.php sudo nano /var/www/cloud/config/config.php # Add your domain to the trusted_domains array: 'trusted_domains' => array ( 0 => 'localhost', 1 => '192.168.1.22', 2 => 'your-domain.com', ), # For other applications, check documentation for: # - Virtual host configuration # - Allowed hosts settings # - CORS configuration # - Security headers
🔧
Application Specific
Each web application has different ways to configure trusted domains. Check your application's documentation.
✓

Verify and Monitor

Confirm everything is working and set up monitoring to catch future issues.

# Check service status sudo systemctl status cloudflared # Monitor live logs sudo journalctl -u cloudflared -f # Test complete functionality curl -I https://your-domain.com curl -I https://your-domain.com/your-app-path # List active tunnels cloudflared tunnel list # Check tunnel info cloudflared tunnel info YOUR_TUNNEL_ID
🎉
Success Indicators
Service shows "active (running)", no error logs, your domain responds with 200 OK, and your application loads properly.
🚨

Emergency Token Method

If credentials files continue to fail, use the token method as a reliable fallback approach.

# Generate tunnel token TOKEN=$(cloudflared tunnel token YOUR_TUNNEL_ID) # Create service using token instead of config file sudo tee /etc/systemd/system/cloudflared.service > /dev/null << EOF [Unit] Description=cloudflared After=network.target [Service] TimeoutStartSec=0 Type=notify ExecStart=/usr/local/bin/cloudflared tunnel --no-autoupdate run --token $TOKEN Restart=always RestartSec=5s [Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl restart cloudflared
🔑
Token Method Pros/Cons
Tokens are more reliable but harder to manage. Use when credentials files consistently fail.