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

• 404 Error: DNS record pointing to wrong tunnel ID or missing entirely
• Credentials File Missing: Service fails to start due to missing JSON credentials
• Certificate Path Errors: Origin certificate in wrong location or permissions
• Service Restart Loops: Systemd service continuously failing and restarting
• Untrusted Domain Error: Application not configured to accept the new domain

#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:80Copy

Common Error Messages

Look for: "Tunnel credentials file doesn't exist", "Cannot determine default origin certificate", "Failed to start", or "Access through untrusted domain"

#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/cloudflaredCopy

Complete Reset Warning

This removes ALL tunnel configurations. You'll need to delete the old tunnel in Cloudflare dashboard and create a new one.

#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-8011f027dd47Copy

Success Indicators

You should see "Created tunnel [name] with id [uuid]" and credentials file created in ~/.cloudflared/

#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.jsonCopy

Configuration Tips

Replace YOUR_TUNNEL_ID with the actual tunnel ID from step 3. Make sure your-domain.com matches your actual domain.

#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 testCopy

Success Indicators

Look for "Registered tunnel connection" entries with different connection IDs and IP addresses.

#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 cloudflaredCopy

Service Configuration

The service includes automatic restart and proper timing to handle network connectivity issues.

#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.comCopy

DNS Update Critical

This is the most common failure point. Old DNS records pointing to deleted tunnels cause 404 errors.

#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 headersCopy

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_IDCopy

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 cloudflaredCopy

Token Method Pros/Cons

Tokens are more reliable but harder to manage. Use when credentials files consistently fail.