Troubleshooting

SSH Connection Failures

Error: Cannot connect to server

Verify your SSH key and server details.

# Test SSH manually
ssh -i ~/.ssh/id_ed25519 [email protected] "echo ok"

# Check if the key has a passphrase (use ssh-agent)
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Verify the server port is open
nc -zv 1.2.3.4 22

Build Failures

# Force a clean rebuild (no cache)
lift push --force

# Check build logs for errors
lift logs --tail 200

# Verify Dockerfile locally first
docker build -t test .

Health Check Failures

Error: "Connection refused" or "HTTP unknown" after deploy

The health check couldn't reach your app. The cause depends on your deployment mode.

Without domain (direct port access)

Health check connects to 127.0.0.1:PORT on the host. The container port must be published.

# 1. MOST COMMON: ensure expose is true in .lift.json
#    Without expose:true, port isn't published = "Connection refused"
#    Edit .lift.json: "expose": true

# 2. Verify port is published
lift ssh -- docker port my-app-1
# Should show: 3000/tcp -> 0.0.0.0:3000

# 3. Ensure app listens on 0.0.0.0 (not 127.0.0.1)
lift env set HOST=0.0.0.0

With domain (Traefik routing)

Health check resolves container's internal IP via docker inspect. Port publishing is not needed.

# 1. Verify Traefik is running
lift ssh -- docker ps -f name=traefik

# 2. Check container is on correct Docker network
lift ssh -- docker inspect my-app-1 --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}'

General

# Check container status and logs
lift status --all
lift logs --tail 50

# Test from inside the container
lift exec -- curl -s http://127.0.0.1:3000/

# Force rebuild and redeploy
lift push --force

Port Conflicts

# Check what's using a port on the server
lift exec --container my-app-1 -- ss -tlnp

# List all containers and their ports
lift status --all

Disk Space Issues

# Run diagnostics
lift doctor

# Clean up Docker resources on the server
lift exec --container my-app-1 -- docker system prune -af

Rate Limit Errors

Error (429): "Rate limit exceeded for install operations"

You've hit the hourly action limit for your tier.

# Check the Retry-After header or resetSec in the response body
# Wait the indicated time before retrying

# If you consistently hit limits, upgrade your plan
# Free: 10 installs/hr, Starter: 20/hr, Pro: 50/hr

Error (409): "This operation is already running for this project"

A duplicate job was submitted while the previous one is still in progress.

# Wait for the current operation to finish
# Check project status in the dashboard or via CLI
lift status

Error (429): "Please wait before repeating this action"

Endpoint debounce — you clicked too fast. Wait 3 seconds.

Error (429): "System is busy. Please try again later."

The job queue is at capacity. Try again in ~60 seconds.

Preview Port Exhaustion

# List active previews
lift push --list

# Stop old previews (7+ days old are flagged)
lift push --stop old-feature-branch