CyberPanel n8n Docker App Debugging Guide

Support and Discussion
1

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.

:warning: 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:

  1. User fills form on “Create Docker App” page

  2. CyberPanel validates site name, resources, domain

  3. Background deployment starts (0-100% progress)

  4. Docker installation check (0-20%)

  5. Resource verification (20-30%)

  6. Directory creation (30-40%)

  7. Docker compose generation (40-60%)

  8. Container deployment (60-80%)

  9. Health checks and proxy setup (80-100%)

  10. 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:

  1. Open browser Developer Tools (F12)

  2. Go to Console tab

  3. Try creating n8n app

  4. 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:

  1. Wait 5-10 minutes (some steps take time)

  2. Check system load - if high, wait for it to decrease

  3. 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:

  1. Check firewall: firewall-cmd --list-ports

  2. Restart containers: docker-compose restart

  3. Check domain DNS resolution

  4. 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:

  1. Restart database: docker-compose restart db

  2. Wait for database to fully initialize (can take 2-3 minutes)

  3. 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:

  1. Reduce resource allocation in CyberPanel form

  2. Stop other containers: docker stop $(docker ps -q)

  3. 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:

  1. This indicates missing API endpoints in CyberPanel

  2. Check CyberPanel version and update if needed

  3. 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.

1 Like