Troubleshooting
Fixes for the most common TLD issues.
Start with tld doctor
Run `tld doctor` first. It diagnoses the most common issues automatically and tells you exactly what's wrong.Docker not running
Error: Cannot connect to the Docker daemon
bash
# Start Docker
$ sudo systemctl start docker # Linux (systemd)
$ open -a Docker # macOS (Docker Desktop)
# Verify Docker is running
$ docker info
Permission denied
Error: Got permission denied while trying to connect to the Docker daemon socket
bash
# Add your user to the docker group (Linux only)
$ sudo usermod -aG docker $USER
# Apply the group change (log out and back in, or:)
$ newgrp docker
# Verify
$ docker ps
Port already in use
Error: Bind for 0.0.0.0:8080 failed: port is already allocated
bash
# Find what's using the port
$ lsof -i :8080
# or
$ ss -tlnp | grep 8080
# Kill the process
$ sudo kill $(lsof -t -i:8080)
# Or stop any running lab containers
$ tld lab stop
$ docker ps -q | xargs docker stop
WSL2 issues
WSL2 requirements
You must use WSL2 (not WSL1). Docker Desktop must have WSL2 integration enabled for your distro.bash
# Check WSL version
$ wsl --list --verbose
# Should show VERSION 2 for your distro
# Upgrade a distro to WSL2
$ wsl --set-version Ubuntu-22.04 2
# Verify Docker is accessible inside WSL
$ docker info
Authentication issues
bash
# Clear cached credentials and re-authenticate
$ tld logout
$ tld login
# If login fails, check network connectivity
$ curl https://api.thelastdeploy.com/health
Run tld doctor
bash
$ tld doctor
# Sample output:
# ✓ Docker daemon is running (24.0.5)
# ✓ Docker socket is accessible
# ✓ Current user is in docker group
# ✗ Disk space low: 2.1GB free (recommend 10GB+)
# ✓ Network connectivity OK
# ✓ TLD CLI is up to date (v0.1.2)
#
# 1 issue found. See above for details.
If tld doctor doesn't identify your issue, open a GitHub issue or ask in Discord with the full output of tld doctor and a description of what you were doing when the error occurred.