The Free Encyclopedia
Log in
Article History

Cloudflare Tunnel Troubleshooting Guide

Revision as of Jun 25, 2026 23:43 by migration.

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: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"

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.

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/

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.

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.

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.

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.

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.