Troubleshooting

This guide covers common issues you might encounter when using Surge and their solutions.

Server Already Running

Problem

Error: Surge server is already running.

This occurs when you try to start a server instance while another is already active.

Solution

Check if server is running

surge server status

Stop the existing server

surge server stop

Or find and kill the process manually:

# Linux/macOS
ps aux | grep surge
kill <pid>

# Windows
tasklist | findstr surge
taskkill /PID <pid> /F

Start the server again

surge server

Surge uses a lock file to prevent multiple instances. The lock file is located at:

Linux/macOS: ~/.config/surge/runtime/surge.lock
Windows: %APPDATA%\surge\runtime\surge.lock

Stale Lock File

If the server crashed without cleaning up, you may have a stale lock file:

# Linux/macOS
rm ~/.config/surge/runtime/surge.lock

# Windows
del %APPDATA%\surge\runtime\surge.lock

Only remove the lock file if you’re certain no Surge process is running. Check with surge server status first.

Port Already in Use

Problem

Error: failed to bind server listener: address already in use

Another application is using Surge’s default port (1700).

Solution

Option 1: Use a Different Port

# Start Surge on a custom port
surge server --port 8080

# Connect to custom port
surge connect localhost:8080

# CLI commands with custom port
surge --host localhost:8080 ls

Option 2: Find and Stop the Conflicting Process

Linux/macOS:

# Find process using port 1700
lsof -i :1700

# Or with netstat
netstat -tulpn | grep :1700

# Kill the process
sudo kill -9 <pid>

Windows:

# Find process using port 1700
netstat -ano | findstr :1700

# Kill the process
taskkill /PID <pid> /F

Option 3: Check for Previous Surge Instance

# Check server status
surge server status

# Stop if running
surge server stop

Connection Refused

Problem

Error: surge is not running locally. start it or pass --host (or set SURGE_HOST)

Error: failed to connect to server: connection refused

Solution

Verify server is running

surge server status

Start the server if needed

surge server

Check the port file

# Linux/macOS
cat ~/.config/surge/runtime/port

# Windows
type %APPDATA%\surge\runtime\port

The file should contain the port number (e.g., 1700).

If connecting remotely, verify host/port

# Test connection
curl http://<server-ip>:1700/health

# Should return: {"status":"ok","port":1700}

For remote connections, ensure:

The server is bound to 0.0.0.0 (Surge does this by default)
Firewall allows incoming connections on the port
You’re using the correct host:port combination

Authentication Failed

Problem

Error: 401 Unauthorized

Your API token is invalid or missing.

Solution

Get the correct token

# On the server machine
surge token

Set the token for CLI commands

# Option 1: Environment variable
export SURGE_TOKEN="your-token-here"

# Option 2: Command flag
surge --token "your-token-here" ls

Verify authentication works

curl http://localhost:1700/list \
  -H "Authorization: Bearer $(surge token)"

Token location:

Linux/macOS: ~/.config/surge/token
Windows: %APPDATA%\surge\token

Permission Denied

Problem

Error: permission denied: /path/to/download/file.zip

Surge cannot write to the output directory.

Solution

Option 1: Fix Directory Permissions

# Linux/macOS: Make directory writable
chmod 755 ~/Downloads
sudo chown $USER:$USER ~/Downloads

# Verify permissions
ls -la ~/Downloads

Option 2: Use Different Output Directory

# Specify writable directory
surge add https://example.com/file.zip --output ~/Documents

# Or for server mode
surge server --output ~/Documents

Option 3: Run with Appropriate Privileges (Not Recommended)

# Linux/macOS (avoid if possible)
sudo surge server

# Better: Create downloads directory with proper ownership
mkdir -p ~/surge-downloads
surge server --output ~/surge-downloads

Avoid running Surge as root/administrator unless absolutely necessary. Instead, fix directory permissions or use a different output path.

Database Locked

Problem

Error: database is locked

Multiple processes are trying to access Surge’s database simultaneously.

Solution

Stop all Surge instances

# Stop server
surge server stop

# Check for other processes
ps aux | grep surge

Wait a few seconds

The database lock should release automatically.

Restart Surge

surge server

If the problem persists:

# Check for stale database locks
ls -la ~/.config/surge/*.db*

# Remove lock files (only if no Surge process is running!)
rm ~/.config/surge/*.db-shm
rm ~/.config/surge/*.db-wal

Download Stuck or Not Starting

Problem

Download shows pending or downloading but makes no progress.

Solution

Check download details

surge ls <download-id> --json

Look for error messages in the output.

Verify the URL is accessible

curl -I https://example.com/file.zip

Check for:

200 OK response
Content-Length header
No authentication requirements

Try pausing and resuming

surge pause <download-id>
surge resume <download-id>

If URL expired, refresh it

surge refresh <download-id> https://new-url.com/file.zip
surge resume <download-id>

For cloud storage links (Google Drive, OneDrive, S3):

URLs often expire after a few hours
Generate a fresh download link
Use the refresh command to update without losing progress

SSL/TLS Certificate Errors

Problem

Error: x509: certificate signed by unknown authority

Solution

Update System Certificates

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install ca-certificates
sudo update-ca-certificates

Linux (RHEL/Fedora):

sudo yum update ca-certificates

macOS:

brew install ca-certificates

Skip Certificate Verification (Not Recommended)

For testing or internal servers only:

# This is insecure - use only for trusted internal networks
export GODEBUG=x509ignoreCN=0
surge add https://untrusted.example.com/file.zip

High Memory Usage

Problem

Surge consumes excessive RAM during downloads.

Solution

Reduce concurrent downloads

Pause some downloads to free up resources:

surge pause --all
surge resume <specific-id>

Reduce worker count (if supported in config)

Edit Surge configuration to limit workers per download:

# Check current settings
surge ls <download-id> --json | jq .workers

Restart Surge periodically

For long-running server instances:

surge pause --all
surge server stop
surge server
surge resume --all

Memory usage is typically proportional to:

Number of concurrent downloads
Number of workers per download (up to 32)
File buffer sizes

Disk Space Issues

Problem

Error: no space left on device

Solution

Check available disk space

# Linux/macOS
df -h ~/Downloads

# Windows
dir

Free up space

# Remove completed downloads from queue
for id in $(surge ls --json | jq -r '.[] | select(.status == "completed") | .id'); do
  surge rm $id
done

Change output directory

# Use a different drive/partition
surge add https://example.com/file.zip --output /mnt/external

Surge pre-allocates disk space for downloads (when supported by the filesystem). Ensure you have enough free space before starting large downloads.

Network Issues

Problem

Slow speeds, timeouts, or connection drops.

Solution

Check Internet Connection

# Test connectivity
ping -c 4 8.8.8.8

# Test DNS resolution
nslookup example.com

# Test download speed
curl -o /dev/null https://speed.cloudflare.com/__down?bytes=100000000

Use Mirrors

# Download from multiple sources
surge add "https://primary.com/file.zip,https://mirror1.com/file.zip,https://mirror2.com/file.zip"

Check Firewall

# Linux: Check firewall rules
sudo iptables -L
sudo ufw status

# Windows: Check Windows Firewall
netsh advfirewall show allprofiles

Pause and Resume

# If connection is unstable
surge pause --all
# Wait for network to stabilize
surge resume --all

Configuration File Errors

Problem

Error: failed to load config

Solution

Locate config files

# Linux/macOS
ls -la ~/.config/surge/

# Windows
dir %APPDATA%\surge

Backup and reset

# Linux/macOS
mv ~/.config/surge ~/.config/surge.backup
surge server  # Creates fresh config

# Windows
move %APPDATA%\surge %APPDATA%\surge.backup
surge server

Restore settings if needed

Copy specific files from backup:

# Restore token only
cp ~/.config/surge.backup/token ~/.config/surge/

Getting Help

If you’re still experiencing issues:

Enable verbose logging

surge --verbose server

Check debug information

# Server status
surge server status

# Download details
surge ls --json

# Version info
surge --version

Report the issue

Visit the GitHub Issues page with:

Surge version (surge --version)
Operating system
Full error message
Steps to reproduce

For discussions and community support, check out the GitHub Discussions page.

Get Started

Core Concepts

Guides

Advanced

​Server Already Running

​Problem

​Solution

​Stale Lock File

​Port Already in Use

​Problem

​Solution

​Connection Refused

​Problem

​Solution

​Authentication Failed

​Problem

​Solution

​Permission Denied

​Problem

​Solution

​Database Locked

​Problem

​Solution

​Download Stuck or Not Starting

​Problem

​Solution

​SSL/TLS Certificate Errors

​Problem

​Solution

​High Memory Usage

​Problem

​Solution

​Disk Space Issues

​Problem

​Solution

​Network Issues

​Problem

​Solution

​Configuration File Errors

​Problem

​Solution

​Getting Help

Server Already Running

Problem

Solution

Stale Lock File

Port Already in Use

Problem

Solution

Connection Refused

Problem

Solution

Authentication Failed

Problem

Solution

Permission Denied

Problem

Solution

Database Locked

Problem

Solution

Download Stuck or Not Starting

Problem

Solution

SSL/TLS Certificate Errors

Problem

Solution

High Memory Usage

Problem

Solution

Disk Space Issues

Problem

Solution

Network Issues

Problem

Solution

Configuration File Errors

Problem

Solution

Getting Help