Reference

Troubleshooting & Common Fixes

Resolving common operational issues, Docker permissions, and boot errors.

1. Production Boot: Insecure JWT Secret Error

Symptom: The server exits immediately with 'Refusing to boot in production with default JWT secret'.

# Fix: Generate a secure 256-bit random string and set NINEDEPLOY_JWT_SECRET in .env
openssl rand -hex 32
# Add to .env:
# NINEDEPLOY_JWT_SECRET=c9a0...3f2

2. Docker Daemon Permission Denied

Symptom: 'connect: permission denied' when communicating with /var/run/docker.sock.

# Ensure the service user belongs to the 'docker' group:
sudo usermod -aG docker $USER
newgrp docker
# For Docker-in-Docker containers, verify the socket volume mount:
# -v /var/run/docker.sock:/var/run/docker.sock

3. SQLite Database Locked or Busy

Symptom: 'SQLITE_BUSY: database is locked'.

# NineDeploy uses synchronous file locks. Ensure only one NineDeploy instance is accessing the .data directory.
# If a previous crashed process holds a lock, verify no zombie processes:
pgrep -fl ninedeploy
# Restart the systemd service cleanly:
sudo systemctl restart ninedeploy

4. Port 80/443 Conflicts with Existing Nginx/Apache

Symptom: Traefik container fails to bind port 80 or 443.

# Check which process is occupying port 80/443:
sudo ss -tulpn | grep -E ':(80|443)'
# Stop or disable conflicting standalone web servers:
sudo systemctl stop nginx
sudo systemctl disable nginx

5. Remote Node Agent Connection Refused

Symptom: Controller reports 'Agent unreachable' when querying remote node.

# Check that the agent is running on the remote host:
curl http://<remote-node-ip>:3001/health
# Verify firewall allows port 3001 from the controller IP:
sudo ufw allow from <controller-ip> to any port 3001 proto tcp

6. Docker Pull Exits with Code 143 (SIGTERM)

Exit 143 means an external supervisor sent SIGTERM. Older NineDeploy Type=notify/WatchdogSec units could terminate the service cgroup during a long image pull. OOM kills normally surface as exit 137.

# Upgrade in place; this migrates and verifies the systemd policy:
curl -fsSL https://ninedeploy.com/install.sh | bash

# Expected: Type=simple and WatchdogUSec=0
systemctl show ninedeploy -p Type -p WatchdogUSec

The canonical guides live in the repository's docs folder.