Troubleshooting

​

Quick Diagnostics

​

Check Service Status

# Docker installation
docker ps
docker compose -f production.docker-compose.yml ps

# Standalone installation
pm2 status
# or
systemctl status snailycad-api snailycad-client

​

View Logs

# Docker - all services
docker compose -f production.docker-compose.yml logs

# Docker - specific service
docker logs snaily-cad-api
docker logs snaily-cad-client
docker logs snaily-cad-postgres

# Docker - follow logs in real-time
docker logs -f snaily-cad-api

# Standalone
pm2 logs
pm2 logs snailycad-api

​

Installation Issues

​

Docker Network Error

docker network create cad_web
docker compose -f production.docker-compose.yml up -d

​

Database Connection Failed

1. Check database is running:
   docker ps | grep postgres
   # or
   systemctl status postgresql
   
2. Verify environment variables:
   # Check DATABASE_URL format (.env.example:86)
   DATABASE_URL=postgresql://user:password@host:port/database?sslmode=prefer
   
   # Docker: DB_HOST should be "postgres" (container name)
   # Standalone: DB_HOST should be "localhost" or IP
   
3. Test database connection:
   # Docker
   docker exec snaily-cad-postgres psql -U postgres -d snaily-cad-v4 -c "SELECT 1;"
   
   # Standalone
   psql -U postgres -h localhost -d snaily-cad-v4 -c "SELECT 1;"
   

​

Port Already in Use

# Find what's using the port
lsof -i :3000  # Client port
lsof -i :8080  # API port
lsof -i :5432  # PostgreSQL port

# Update .env.example:72-79
PORT_API=8080
PORT_CLIENT=3000

# Or stop conflicting service
sudo systemctl stop apache2  # If using port 80

​

Node Version Mismatch

# Check Node version
node --version

# Install correct version
nvm install 20
nvm use 20

# Or use Docker (uses node:20-slim)

​

PNPM Not Found

# Install pnpm globally
npm install -g [email protected]

# Verify installation
pnpm --version

​

Runtime Issues

​

500 Internal Server Error

1. Check API logs:
   docker logs snaily-cad-api
   
2. Verify environment variables:
   • JWT_SECRET must be set (.env.example:35)
   • ENCRYPTION_TOKEN must be 32 characters (.env.example:41)
   • CORS_ORIGIN_URL matches client URL (.env.example:47)
3. Check database migrations:
   docker exec snaily-cad-api pnpm prisma migrate status
   
   # Apply pending migrations
   docker exec snaily-cad-api pnpm prisma migrate deploy
   
4. Regenerate Prisma client:
   docker exec snaily-cad-api pnpm prisma generate
   docker compose -f production.docker-compose.yml restart api
   

​

CORS Errors

# These must match your actual URLs
CORS_ORIGIN_URL="http://your-domain.com:3000"
NEXT_PUBLIC_CLIENT_URL="http://your-domain.com:3000"
NEXT_PUBLIC_PROD_ORIGIN="http://your-domain.com:8080/v1"

# Or use wildcard for testing (NOT recommended for production)
CORS_ORIGIN_URL="*"

docker compose -f production.docker-compose.yml restart

​

Authentication Issues

1. Check JWT_SECRET:
   # Verify JWT_SECRET is set and not default value
   # .env.example:35
   JWT_SECRET="some-random-string-of-characters"  # Change this!
   
2. Check cookie settings:
   # If using HTTPS and domain (.env.example:67-70)
   DOMAIN="yourdomain.com"
   SECURE_COOKIES_FOR_IFRAME="true"  # Only with HTTPS
   
3. Clear browser cache and cookies
4. Check for clock skew (server time vs. client time)

​

File Upload Failures

1. Check volume permissions (production.docker-compose.yml:34):
   # Docker - ensure proper ownership
   sudo chown -R 1000:1000 apps/api/public
   
   # Standalone - ensure proper ownership
   sudo chown -R www-data:www-data apps/api/public
   
2. Verify volume mount:
   # Check if volume is mounted
   docker inspect snaily-cad-api | grep -A 5 Mounts
   
3. Check disk space:
   df -h
   
4. Check upload limits in reverse proxy configuration

​

Database Migration Errors

1. Check migration status:
   cd apps/api
   pnpm prisma migrate status
   
2. Resolve migration conflicts:
   # Mark migration as applied (if manually fixed)
   pnpm prisma migrate resolve --applied "migration_name"
   
   # Mark migration as rolled back
   pnpm prisma migrate resolve --rolled-back "migration_name"
   
3. Reset database (WARNING: destroys all data):
   pnpm prisma migrate reset
   
4. Restore from backup and reapply migrations: See Backup & Restore guide.

​

Performance Issues

​

Slow Database Queries

1. Check database size:
   docker exec snaily-cad-postgres psql -U postgres -d snaily-cad-v4 -c "SELECT pg_size_pretty(pg_database_size('snaily-cad-v4'));"
   
2. Analyze slow queries:
   # Enable query logging in PostgreSQL
   # Check logs for slow queries
   docker logs snaily-cad-postgres | grep "duration"
   
3. Optimize database:
   docker exec snaily-cad-postgres psql -U postgres -d snaily-cad-v4 -c "VACUUM ANALYZE;"
   
4. Add database indexes (check apps/api/prisma/schema.prisma for index opportunities)

​

High Memory Usage

1. Check resource usage:
   # Docker
   docker stats
   
   # Standalone
   pm2 monit
   htop
   
2. Limit container memory:
   production.docker-compose.yml

   services:
     api:
       # Add memory limit
       mem_limit: 2g
       mem_reservation: 1g
   
3. Optimize Node.js memory:
   # Increase heap size if needed
   NODE_OPTIONS="--max-old-space-size=4096"
   
4. Check for memory leaks in application logs

​

Disk Space Full

1. Check disk usage:
   df -h
   du -sh /var/lib/docker
   du -sh ./.data  # PostgreSQL data
   
2. Clean Docker resources:
   # Remove unused images
   docker image prune -a
   
   # Remove unused volumes
   docker volume prune
   
   # Remove build cache
   docker builder prune -a
   
3. Clean old logs:
   # Docker logs can grow large
   truncate -s 0 /var/lib/docker/containers/*/*-json.log
   
4. Clean old backups:
   # Remove backups older than 30 days
   find /backups -type f -mtime +30 -delete
   

​

Update Issues

​

Build Fails After Update

1. Clear build cache:
   # Docker
   docker builder prune -a
   docker compose -f production.docker-compose.yml build --no-cache
   
   # Standalone
   rm -rf node_modules
   rm -rf apps/*/node_modules
   rm -rf packages/*/node_modules
   pnpm install
   
2. Check Node version (must be >= 18.16.0)
3. Update pnpm:
   npm install -g [email protected]
   
4. Check for missing environment variables in release notes

​

Containers Won’t Start After Update

1. Check logs:
   docker compose -f production.docker-compose.yml logs
   
2. Verify environment variables match new requirements
3. Check database migrations:
   docker logs snaily-cad-api | grep -i migration
   
4. Rollback if necessary: See Updating SnailyCAD

​

Data Loss After Update

1. Stop all services immediately
2. Check if data still exists in database:
   docker exec snaily-cad-postgres psql -U postgres -d snaily-cad-v4 -c "SELECT COUNT(*) FROM \"User\";"
   
3. Restore from backup: See Backup & Restore
4. Contact support on Discord with detailed logs

​

Networking Issues

​

Reverse Proxy Not Working

1. Verify containers are running:
   docker ps
   
2. Check reverse proxy configuration:
   • Nginx: /etc/nginx/sites-available/snailycad
   • Apache: /etc/apache2/sites-available/snailycad.conf
   • Caddy: /etc/caddy/Caddyfile
3. Verify proxy passes to correct ports:
   • Client: Port from PORT_CLIENT (.env.example:78)
   • API: Port from PORT_API (.env.example:75)
4. Check firewall rules:
   sudo ufw status
   sudo iptables -L
   

​

SSL/TLS Certificate Issues

1. Verify certificate files exist
2. Check certificate validity:
   openssl x509 -in /path/to/cert.pem -noout -dates
   
3. Renew Let’s Encrypt certificate:
   sudo certbot renew
   
4. Update SECURE_COOKIES_FOR_IFRAME (.env.example:70) only when using HTTPS

​

WebSocket Connection Failed

1. Check WebSocket configuration in reverse proxy
2. Verify Socket.IO connection in browser console
3. Check firewall allows WebSocket connections
4. Ensure reverse proxy passes WebSocket headers:
   proxy_http_version 1.1;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";
   

​

Common Error Messages

​

”JWT_SECRET must be set”

JWT_SECRET="your-secure-random-string-here"

​

“ENCRYPTION_TOKEN must be 32 characters”

ENCRYPTION_TOKEN="$(openssl rand -base64 32 | head -c 32)"

​

“Database does not exist”

docker exec snaily-cad-postgres psql -U postgres -c "CREATE DATABASE \"snaily-cad-v4\";"

​

“Port is already allocated”

# Find what's using the port
sudo lsof -i :3000

# Kill the process or change PORT_CLIENT in .env

​

“Network cad_web not found”

docker network create cad_web

​

“Permission denied” on file uploads

sudo chown -R 1000:1000 apps/api/public
# or
sudo chmod -R 755 apps/api/public

​

Getting Help

​

Gathering Information

1. Version information:
   # SnailyCAD version (package.json:4)
   cat package.json | grep version
   
   # Node version
   node --version
   
   # Docker version (if applicable)
   docker --version
   
2. Error logs:
   # Last 100 lines of API logs
   docker logs --tail 100 snaily-cad-api
   
   # Last 100 lines of client logs
   docker logs --tail 100 snaily-cad-client
   
3. Environment (Docker vs Standalone)
4. Installation method
5. Recent changes (updates, configuration changes)

​

Support Channels

• Discord: Join Discord - Active community support
• GitHub Issues: Report bugs
• Documentation: docs.snailycad.org

​

Before Asking for Help

1. Check this troubleshooting guide
2. Search existing GitHub issues
3. Search Discord for similar problems
4. Verify you’re on the latest version
5. Check your configuration against .env.example
6. Review application logs

​

Preventive Maintenance

​

Regular Tasks

1. Backup regularly - See Backup & Restore
2. Update dependencies - Keep Node.js, Docker, and PostgreSQL updated
3. Monitor disk space - Ensure adequate free space
4. Review logs - Check for warnings or errors
5. Test backups - Verify restore procedures work
6. Update SnailyCAD - Stay current with latest version

​

Health Checks

#!/bin/bash

# Check if services are running
if ! docker ps | grep -q snaily-cad-api; then
    echo "ERROR: API container not running"
    exit 1
fi

if ! docker ps | grep -q snaily-cad-client; then
    echo "ERROR: Client container not running"
    exit 1
fi

# Check if API responds
if ! curl -f http://localhost:8080/v1/admin/manage/cad-settings > /dev/null 2>&1; then
    echo "WARNING: API not responding"
fi

# Check disk space
DISK_USAGE=$(df -h / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $DISK_USAGE -gt 80 ]; then
    echo "WARNING: Disk usage is ${DISK_USAGE}%"
fi

echo "Health check passed"

​

Next Steps

• Updating SnailyCAD - Keep your installation current
• Backup & Restore - Protect your data
• Environment Variables - Configuration reference
• Discord Support - Get help from the community