Step-by-step solutions for common tunnel setup failures and configuration issues
Cloudflare Tunnel Troubleshooting Guide
Revision as of Jun 25, 2026 22:26 by migration.
This is an old revision — view current.
Contents
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
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.