Troubleshooting Guide

May 16, 2026 · View on GitHub

Solutions for common DevBox issues.

SSH Issues
Service Issues
Tailscale Issues
Ollama Issues
Docker Issues
VPN Issues
Performance Issues

SSH Issues

Connection Refused

Symptoms: ssh: connect to host ... port 5522: Connection refused

Diagnosis:

# On server (via console or recovery)
sudo systemctl status ssh
sudo ss -tlnp | grep ssh

Solutions:

Verify SSH is running:

sudo systemctl start ssh
sudo systemctl enable ssh

Check correct port:

grep "^Port" /etc/ssh/sshd_config
# Should show: Port 5522

Verify firewall:

sudo ufw status
sudo ufw allow 5522/tcp

Permission Denied (publickey)

Symptoms: Permission denied (publickey)

Solutions:

Verify your key is in authorized_keys:
```
cat ~/.ssh/authorized_keys
```

Check permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Verify correct key on client:

ssh -i ~/.ssh/id_ed25519 -p 5522 dev@server

Connection Timeout

Symptoms: Connection hangs, no response

Solutions:

Verify server IP is correct
Check if server is online (ping from another source)
Verify port 5522 is open in cloud provider firewall

Service Issues

Services Not Accessible

Symptoms: Cannot access ai.internal, traefik.internal, etc.

Diagnosis:

# Check containers are running
docker ps

# Check Traefik logs
docker logs traefik

# Test internal routing
curl -H "Host: ai.internal" http://localhost

Solutions:

Verify containers are running:
```
cd ~/docker
./start-all.sh
```

Check Traefik configuration:

docker logs traefik 2>&1 | grep -i error

Verify DNS entries on client:
```
cat /etc/hosts | grep internal
```
Tailscale port binding: Ports 80 and 443 are bound to the Tailscale IP — they are intentionally inaccessible from LAN or the public internet. You must connect via Tailscale to reach services. Verify:
```
ss -tlnp | grep ':80\|:443'   # Should show TAILSCALE_IP, not 0.0.0.0
tailscale status               # Verify Tailscale is connected
```

Container Won't Start

Diagnosis:

docker ps -a                    # Check status
docker logs container-name      # Check logs
docker inspect container-name   # Check configuration

Common causes:

Port conflict: Another service using the same port
Volume permissions: Check directory ownership
Network issues: Verify network exists
```
docker network ls | grep proxy-net
```

Open WebUI Not Loading

Symptoms: 502 Bad Gateway or blank page

Solutions:

Check Open WebUI container:
```
docker logs openwebui
```
Verify Ollama is running:
```
docker exec -it ollama ollama list
```

Restart services:

cd ~/docker/ollama-openwebui
docker compose down && docker compose up -d

Tailscale Issues

Authentication Failed

Symptoms: Cannot complete Tailscale authentication

Solutions:

sudo tailscale logout
sudo tailscale up --accept-routes

Open the provided URL in your browser to re-authenticate.

Cannot Reach Other Devices

Diagnosis:

tailscale status         # Check connection
tailscale ping device    # Test connectivity

Solutions:

Verify both devices are online in Tailscale admin
Check ACLs in Tailscale admin console
Restart Tailscale:
```
sudo systemctl restart tailscaled
```

MagicDNS Not Working

Symptoms: Cannot resolve device names

Solutions:

Enable MagicDNS in Tailscale admin console
Verify DNS settings:
```
tailscale status --json | jq '.DNS'
```

Ollama Issues

Models Not Loading

Diagnosis:

docker exec -it ollama ollama list
docker logs ollama

Solutions:

Pull model again:

docker exec -it ollama ollama pull model-name

Check disk space:
```
df -h /var/lib/docker
```
Restart Ollama:
```
docker restart ollama
```

Out of Memory

Symptoms: Model crashes or fails to load

Solutions:

Use smaller model:

docker exec -it ollama ollama pull llama3.2:1b

Check memory usage:
```
docker stats ollama
```
Increase container memory limit in docker-compose.yml

Slow Responses

Causes and solutions:

No GPU: Check if GPU is detected
```
docker logs ollama 2>&1 | grep -i gpu
```
Large model: Use smaller model or quantized version
Insufficient RAM: Close other applications, use smaller model
Suboptimal configuration: See Ollama Optimization for tuning

Remote Access Not Working

Diagnosis:

# From server
curl http://localhost:11434/api/tags

# From laptop
curl http://TAILSCALE_IP:11434/api/tags

Solutions:

Verify Ollama is bound to Tailscale IP (not localhost)
Check docker-compose.yml ports configuration
See Remote IDE Setup for complete configuration
See Ollama Optimization for port binding options

Docker Issues

Docker Daemon Not Running

Symptoms: Cannot connect to the Docker daemon

Solutions:

sudo systemctl start docker
sudo systemctl enable docker

Permission Denied

Symptoms: permission denied while trying to connect to the Docker daemon

Solutions:

sudo usermod -aG docker $USER
# Log out and back in, or:
newgrp docker

Disk Full

Diagnosis:

df -h
docker system df

Solutions:

# Remove unused resources
docker system prune -af

# Remove unused volumes
docker volume prune -f

# Remove old images
docker image prune -af

Network Issues

Symptoms: Containers cannot communicate

Solutions:

Verify network exists:
```
docker network ls | grep proxy-net
```
Recreate network if needed:
```
docker network create proxy-net
```

Reconnect containers:

cd ~/docker
./stop-all.sh && ./start-all.sh

VPN Issues

HTB VPN Not Connecting

Diagnosis:

htb-vpn status
tail -f /tmp/htb-vpn.log

Solutions:

Verify OVPN file is valid
Check file permissions:
```
chmod 600 ~/htb/*.ovpn
```
Kill existing connection:
```
htb-vpn stop
htb-vpn ~/htb/lab.ovpn
```

No Route to HTB Network

Diagnosis:

ip addr show tun0
ip route | grep tun0

Solutions:

Verify VPN is connected:
```
htb-vpn status
```
Check routing:
```
ip route get 10.10.10.1
```

Exegol Cannot Reach Targets

Solutions:

Launch Exegol with host network:
```
./docker/exegol-start.sh
```
Verify from inside Exegol:
```
ip addr
ping 10.10.10.x
```

Performance Issues

High CPU Usage

Diagnosis:

docker stats
htop

Solutions:

Identify heavy container:
```
docker stats --no-stream
```
Restart problematic service:
```
docker restart container-name
```
Check for runaway processes:
```
docker exec container-name top
```

High Memory Usage

Diagnosis:

free -h
docker stats

Solutions:

Use smaller Ollama models
Reduce container memory limits
Stop unused services:
```
docker stop container-name
```

Slow Disk I/O

Diagnosis:

iostat -x 1
df -h

Solutions:

Check disk usage and clean up
Move Docker data to faster storage
Use SSD for Ollama models

Getting Help

If issues persist:

Check container logs:

docker logs container-name 2>&1 | tail -100

Run security check:
```
cd ~/docker
./security-check.sh
```

Collect system info:

uname -a
docker version
tailscale version

Last updated: 2026-05-16 (v1.0.0)