This guide helps you debug issues specifically with n8n apps deployed through CyberPanel’s “Create Docker App” interface. This is NOT for manual Docker deployments - it’s focused on the CyberPanel-managed n8n deployment workflow.
IMPORTANT: Enable Debug Mode First!
Before you start debugging or attempt another n8n deployment, enable CyberPanel’s debug mode:
sudo touch /usr/local/CyberCP/debug
This creates detailed debug logs in /home/cyberpanel/error_logs.txt
which contain Python stack traces and detailed error information not available in regular logs. This is essential for diagnosing n8n deployment failures.
CyberPanel n8n Deployment Workflow
Understanding the process helps identify where issues occur:
-
User fills form on “Create Docker App” page
-
CyberPanel validates site name, resources, domain
-
Background deployment starts (0-100% progress)
-
Docker installation check (0-20%)
-
Resource verification (20-30%)
-
Directory creation (30-40%)
-
Docker compose generation (40-60%)
-
Container deployment (60-80%)
-
Health checks and proxy setup (80-100%)
-
Completion - redirects to Docker Site Home
Step-by-Step Debugging
Step 1: Check Initial Form Submission
Common Form Validation Errors:
# Check CyberPanel access logs for form submission
tail -f /usr/local/lscp/logs/access.log | grep "submitDockerSiteCreation"
Look for these errors:
-
Site name can only contain lowercase letters and numbers
-
Minimum RAM requirement is 256MB
-
Domain name is already in use
-
Insufficient package resources
-
User lacks permissions to create Docker sites
Quick Fixes:
-
Site name must be lowercase alphanumeric only:
myappname123
-
RAM allocation minimum 256MB for both MySQL and app
-
Ensure domain is not already used for another site
-
Check user’s package limits allow Docker sites
Step 2: Enable CyberPanel Debug Mode
IMPORTANT: Enable CyberPanel Debug Logging First
Before starting the deployment, enable detailed debug logging:
# Enable CyberPanel debug mode
sudo touch /usr/local/CyberCP/debug
# This will generate detailed logs in /home/cyberpanel/error_logs.txt
Track Real-time Deployment:
# Monitor the deployment status file
SITE_NAME="yourappname" # Replace with your site name
watch -n 2 "cat /home/$SITE_NAME.txt 2>/dev/null || echo 'Status file not found'"
Monitor CyberPanel Logs During Deployment:
# Terminal 1: Watch CyberPanel debug logs (MOST IMPORTANT)
tail -f /home/cyberpanel/error_logs.txt
# Terminal 2: Watch access logs
tail -f /usr/local/lscp/logs/access.log
# Terminal 3: Watch error logs
tail -f /usr/local/lscp/logs/error.log
# Terminal 4: Watch for new Docker containers
watch -n 3 "docker ps -a | grep -E '(n8n|postgres)'"
Note: The debug log /home/cyberpanel/error_logs.txt
will show detailed Python stack traces and error messages that are not visible in the regular logs. This is crucial for diagnosing n8n deployment failures.
Step 3: Identify Deployment Stage Failures
Stage 1: Docker Installation (0-20%)
Issue: Failed to install Docker
# Check if Docker is properly installed
systemctl status docker
docker --version
# Check Docker installation logs
journalctl -u docker.service --since "10 minutes ago"
Quick Fix:
# If Docker isn't running
sudo systemctl start docker
sudo systemctl enable docker
Stage 2: Resource Verification (20-30%)
Issue: System does not have sufficient resources
# Check available system resources
free -h # Available memory
df -h # Available disk space
uptime # System load
Requirements:
-
Minimum 1GB free RAM (for 256MB MySQL + 256MB n8n + system overhead)
-
Minimum 2GB free disk space
-
System load under 5.0
Stage 3: Directory Creation (30-40%)
Issue: Failed to create directories
# Check if directories exist and permissions
DOMAIN="yourdomain.com" # Replace with your domain
ls -la /home/docker/
ls -la /home/docker/$DOMAIN/ 2>/dev/null || echo "Directory doesn't exist"
# Check disk permissions
df -h /home
Quick Fix:
# Fix permissions if needed
sudo chown -R cyberpanel:cyberpanel /home/docker/
sudo chmod -R 755 /home/docker/
Stage 4: Docker Compose Generation (40-60%)
Issue: Failed to generate compose file
# Check if compose file was created
DOMAIN="yourdomain.com"
cat /home/docker/$DOMAIN/docker-compose.yml 2>/dev/null || echo "Compose file missing"
# Check file permissions
ls -la /home/docker/$DOMAIN/
Stage 5: Container Deployment (60-80%)
Issue: Failed to deploy containers
# Check Docker compose deployment
DOMAIN="yourdomain.com"
cd /home/docker/$DOMAIN/
# Try manual deployment to see specific errors
docker-compose up -d
# Check for container creation errors
docker-compose logs
# Check container status
docker-compose ps
Common Issues:
-
Port conflicts:
port is already allocated
-
Image pull failures:
failed to pull image
-
Network issues:
network not found
Stage 6: Health Checks (80-100%)
Issue: Containers failed to reach healthy state
DOMAIN="yourdomain.com"
cd /home/docker/$DOMAIN/
# Check container health
docker-compose ps
docker-compose logs n8n
docker-compose logs db
# Check if containers are responding
docker exec -it ${DOMAIN//./_}_n8n_1 curl -f http://localhost:5678/healthz || echo "n8n not responding"
Step 4: Check CyberPanel Frontend Issues
JavaScript Console Errors:
-
Open browser Developer Tools (F12)
-
Go to Console tab
-
Try creating n8n app
-
Look for these common errors:
Missing API Endpoints:
Failed to load resource: GET /docker/getDockersiteList 404 (Not Found)
Failed to load resource: GET /docker/getContainerAppinfo 404 (Not Found)
Failed to load resource: GET /docker/getContainerApplog 404 (Not Found)
AJAX Request Failures:
POST /websites/submitDockerSiteCreation failed
Uncaught TypeError: Cannot read property 'data' of undefined
Check Docker Site Management Page:
# After deployment, visit: https://your-panel.com:8090/websites/dockerSiteHome?domain=yourdomain.com
# Look for:
# - Container status indicators
# - Resource usage displays
# - Action buttons (Start/Stop/Restart)
# - Log viewing functionality
Step 5: Post-Deployment Verification
Check n8n Container Health:
DOMAIN="yourdomain.com"
CONTAINER_NAME="${DOMAIN//./_}_n8n_1"
# Check container status
docker ps | grep $CONTAINER_NAME
# Check n8n logs
docker logs $CONTAINER_NAME
# Test n8n web interface accessibility
curl -I http://localhost:5678 || echo "n8n not accessible"
# Check PostgreSQL connectivity
docker exec -it ${DOMAIN//./_}_db_1 psql -U n8n -d n8n -c "SELECT version();"
Check Reverse Proxy Configuration:
DOMAIN="yourdomain.com"
# Check if virtual host exists
ls -la /usr/local/lsws/conf/vhosts/$DOMAIN/
# Check htaccess configuration
cat /home/docker/$DOMAIN/.htaccess 2>/dev/null || echo "htaccess file missing"
# Test domain accessibility
curl -I https://$DOMAIN || echo "Domain not accessible"
Common Error Scenarios & Solutions
Error 1: “Deployment stuck at X%”
Symptoms: Progress bar stops, no error message
Diagnosis:
# Check the status file
SITE_NAME="yourappname"
cat /home/$SITE_NAME.txt
# Check for hanging processes
ps aux | grep docker
# Check system resources
top
Solutions:
-
Wait 5-10 minutes (some steps take time)
-
Check system load - if high, wait for it to decrease
-
If truly stuck, refresh page and try again
Error 2: “Container exists but not accessible”
Symptoms: Deployment completes but n8n interface doesn’t load
Diagnosis:
DOMAIN="yourdomain.com"
cd /home/docker/$DOMAIN/
# Check container status
docker-compose ps
# Check if n8n is responding internally
docker exec -it ${DOMAIN//./_}_n8n_1 curl http://localhost:5678
# Check port mapping
docker port ${DOMAIN//./_}_n8n_1
Solutions:
-
Check firewall:
firewall-cmd --list-ports
-
Restart containers:
docker-compose restart
-
Check domain DNS resolution
-
Verify reverse proxy configuration
Error 3: “Database connection failed”
Symptoms: n8n starts but shows database errors
Diagnosis:
DOMAIN="yourdomain.com"
cd /home/docker/$DOMAIN/
# Check PostgreSQL container
docker-compose logs db
# Test database connectivity from n8n container
docker exec -it ${DOMAIN//./_}_n8n_1 nc -z db 5432
# Check database credentials
grep -E "(DB_|POSTGRES_)" docker-compose.yml
Solutions:
-
Restart database:
docker-compose restart db
-
Wait for database to fully initialize (can take 2-3 minutes)
-
Check database logs for initialization errors
Error 4: “Resource allocation errors”
Symptoms: System does not have sufficient resources
Diagnosis:
# Check actual resource usage
free -h
df -h
docker stats --no-stream
# Check what resources were requested
grep -E "(cpus|mem_limit)" /home/docker/*/docker-compose.yml
Solutions:
-
Reduce resource allocation in CyberPanel form
-
Stop other containers:
docker stop $(docker ps -q)
-
Free up disk space:
docker system prune
Error 5: “Frontend shows no containers”
Symptoms: Docker Site Home page shows empty or loading forever
Diagnosis:
# Check if API endpoints exist
curl -X GET "https://yourpanel.com:8090/docker/getDockersiteList" \
-H "Cookie: sessionid=your-session-id"
# Check CyberPanel URL configuration
grep -r "getDockersiteList" /usr/local/CyberCP/websiteFunctions/
Solutions:
-
This indicates missing API endpoints in CyberPanel
-
Check CyberPanel version and update if needed
-
Report as bug to CyberPanel developers
Advanced Debugging
Extract Complete Debug Information:
#!/bin/bash
# CyberPanel n8n specific debug collector
DOMAIN="yourdomain.com" # Replace with your domain
DEBUG_DIR="/tmp/cyberpanel_n8n_debug_$(date +%Y%m%d_%H%M%S)"
mkdir -p $DEBUG_DIR
echo "Collecting CyberPanel n8n debugging info for domain: $DOMAIN"
# CyberPanel specific logs
cp /usr/local/lscp/logs/access.log $DEBUG_DIR/cyberpanel_access.log
cp /usr/local/lscp/logs/error.log $DEBUG_DIR/cyberpanel_error.log
# CyberPanel debug logs (most important)
cp /home/cyberpanel/error_logs.txt $DEBUG_DIR/cyberpanel_debug.log 2>/dev/null || echo "Debug log not found - enable with: touch /usr/local/CyberCP/debug" > $DEBUG_DIR/cyberpanel_debug.log
# Deployment status
cp /home/$DOMAIN.txt $DEBUG_DIR/deployment_status.txt 2>/dev/null || echo "No status file" > $DEBUG_DIR/deployment_status.txt
# Docker site configuration
if [ -d "/home/docker/$DOMAIN" ]; then
cp -r /home/docker/$DOMAIN $DEBUG_DIR/docker_site_config/
fi
# Container information
docker ps -a | grep -E "(n8n|postgres)" > $DEBUG_DIR/containers.txt
docker images | grep -E "(n8n|postgres)" > $DEBUG_DIR/images.txt
# Container logs if they exist
for container in $(docker ps -a --format "{{.Names}}" | grep -E "$DOMAIN|n8n"); do
docker logs $container > $DEBUG_DIR/container_${container}.log 2>&1
done
# LiteSpeed virtual host configuration
if [ -d "/usr/local/lsws/conf/vhosts/$DOMAIN" ]; then
cp -r /usr/local/lsws/conf/vhosts/$DOMAIN $DEBUG_DIR/vhost_config/
fi
echo "Debug information collected in: $DEBUG_DIR"
tar -czf cyberpanel_n8n_debug.tar.gz $DEBUG_DIR/
echo "Archive created: cyberpanel_n8n_debug.tar.gz"
Check CyberPanel Database:
# Connect to CyberPanel database
mysql -u root -p cyberpanel
# Check Docker sites table
SELECT * FROM websiteFunctions_dockersite WHERE siteName LIKE '%yoursitename%';
# Check user permissions
SELECT * FROM loginSystem_acl WHERE name = 'createDockerSite';
Quick Recovery Actions
Full Reset for Failed Deployment:
DOMAIN="yourdomain.com"
SITE_NAME="yourappname"
# 1. Stop and remove containers
cd /home/docker/$DOMAIN/ 2>/dev/null && docker-compose down
# 2. Remove directories
rm -rf /home/docker/$DOMAIN/
rm -f /home/$SITE_NAME.txt
# 3. Remove from CyberPanel database
mysql -u root -p cyberpanel -e "DELETE FROM websiteFunctions_dockersite WHERE siteName='$SITE_NAME';"
# 4. Remove virtual host
rm -rf /usr/local/lsws/conf/vhosts/$DOMAIN/
# 5. Restart LiteSpeed
systemctl restart lsws
# Now you can try creating the n8n app again through CyberPanel
Emergency Container Recovery:
DOMAIN="yourdomain.com"
cd /home/docker/$DOMAIN/
# Try to start containers manually
docker-compose up -d
# If that fails, rebuild from scratch
docker-compose down
docker-compose pull
docker-compose up -d --force-recreate
Reporting Issues to Support
When reporting CyberPanel n8n deployment issues, provide:
1. Exact Steps Taken:
-
Domain name used
-
Resource allocation settings (CPU/RAM for MySQL and app)
-
Screenshot of error message in CyberPanel interface
2. Error Information:
-
Deployment percentage where it failed
-
Exact error message from CyberPanel interface
-
Browser console errors (F12 → Console)
3. Log Files:
# MOST IMPORTANT: Enable debug mode first
sudo touch /usr/local/CyberCP/debug
# Then collect these specific files:
- /home/cyberpanel/error_logs.txt (CyberPanel debug log - CRITICAL)
- /usr/local/lscp/logs/access.log (last 100 lines)
- /usr/local/lscp/logs/error.log (last 100 lines)
- /home/yoursitename.txt (deployment status)
- Docker container logs: docker logs container_name
- Docker compose file: /home/docker/yourdomain.com/docker-compose.yml
4. System Information:
# Run these commands and include output:
free -h # Memory usage
df -h # Disk usage
docker --version # Docker version
systemctl status lscpd # CyberPanel service status
cat /usr/local/CyberCP/version.txt # CyberPanel version
Contact Support
Forum: CyberPanel Community Forum - Docker Apps section
GitHub: Create issue with “n8n deployment” label
Required: Always attach debug archive and specify “CyberPanel n8n deployment failure”
This guide is specifically for n8n apps deployed through CyberPanel’s web interface. For manual Docker deployments, use standard Docker troubleshooting guides.