Troubleshooting Guide

Common issues and solutions when using NextDeploy's Native Execution engine.

Connection Issues

SSH connection failed

Error:

Error: SSH connection failed: Permission denied (publickey)

Solution:

# Test SSH connection directly
ssh -i ~/.ssh/id_rsa deploy@YOUR_SERVER_IP

# Generate new SSH key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"

# Copy key to server
ssh-copy-id -i ~/.ssh/id_rsa deploy@YOUR_SERVER_IP

# Update nextdeploy.yml with correct key path

Runtime & Deployment Issues

NextDeploy Daemon Not Responding

Error:

Connection refused to NextDeploy Daemon on port 8443

Solution:

# 1. SSH into your VPS
ssh deploy@YOUR_SERVER_IP

# 2. Check the daemon status
sudo systemctl status nextdeployd

# 3. Restart the daemon if necessary
sudo systemctl restart nextdeployd

# 4. Alternatively, replay the prepare step locally
nextdeploy prepare

Application crashes on startup

Symptoms:

  • Systemd service enters a failed state
  • Health checks fail during deployment
  • 502 Bad Gateway from Caddy

Debug steps:

# 1. Check systemd native logs via NextDeploy CLI
nextdeploy logs --tail 100

# 2. Re-run locally to ensure build succeeds
bun run build && bun run start

# 3. SSH in to check raw application logs
ssh deploy@SERVER journalctl -u nextdeploy-myapp.service -n 50 --no-pager

# 4. Check for missing runtime environment variables
doppler run -- nextdeploy deploy

Port already in use

Error:

Error: listen EADDRINUSE: address already in use :::3000

Solution:

# NextDeploy usually handles port swapping, but if a rogue process exists:

# 1. SSH into the server
ssh deploy@SERVER

# 2. Find the rogue process
sudo lsof -i :3000

# 3. Kill the process
sudo kill -9 PID

Secret Management Issues (Doppler)

Doppler token invalid

Error:

Error: invalid Doppler token

Solution:

# Re-login to Doppler
doppler login

# Verify setup
doppler setup

# Check token
doppler configure get token

Secrets not loading

Error:

Error: DATABASE_URL is not defined

Solution:

# Verify secrets exist in Doppler
doppler secrets

# Force NextDeploy to re-sync environmental variables
nextdeploy deploy --sync-secrets

Need Help?

PreviousCLI Reference
Nextvs Kamal