Help & Troubleshooting

Every Problem,
Exact Solution

Step-by-step fixes with copy-ready commands for every NexaPanel issue. Find your problem below.

25+
Problems Covered
12
Categories
50+
Commands Ready
bash

Auto-Repair — Fixes Most Issues Automatically

bash <(curl -fsSL https://nexapanel.hostganga.com/repair.sh)
📦 Installation ⚙️ Panel & Service 🌐 Web Server 🐘 PHP 🗄️ Database 🔑 License 🔒 SSL / HTTPS 📧 Email ⚡ Node.js / PM2 📁 FTP 💾 Files & Disk 🛡️ Security
📦

Installation Problems

Issues during fresh VPS setup

Installation stuck / failed midway

Install Fail

Root Cause

  • ▸Not enough disk space (need at least 2 GB free)
  • ▸Another apt/dpkg process is locking the package system
  • ▸Network timeout while downloading packages
1

Check available disk space

bash
df -h /
2

Release any stuck package locks

bash
rm -f /var/lib/apt/lists/lock /var/lib/dpkg/lock* /var/cache/apt/archives/lock dpkg --configure -a && apt-get -f install -y
3

Re-run installer (completely safe to re-run)

bash
bash <(curl -fsSL https://nexapanel.hostganga.com/install.sh)

Apache2 crashes during install — "Job for apache2.service failed"

Apache Error

Root Cause

  • ▸Nginx already running on port 80 — Apache2 tries to bind the same port on install
1

Set Apache to port 8080 and disable auto-start

bash
systemctl stop apache2 2>/dev/null || true sed -i 's/^Listen 80$/Listen 8080/' /etc/apache2/ports.conf systemctl disable apache2
2

Switch web server in panel

Panel → Website → Edit → Web Server → Select Apache2 → Save — this will start Apache automatically on port 8080.

Only PHP 8.3 installed — versions 7.4, 8.0, 8.1, 8.2 missing

PHP Versions

Root Cause

  • ▸The ondrej/php PPA was not added — Ubuntu 24.04 default repos only ship PHP 8.3
1

Add the ondrej/php PPA and install all PHP versions

bash
apt-get install -y software-properties-common add-apt-repository -y ppa:ondrej/php && apt-get update for VER in 7.4 8.0 8.1 8.2 8.3; do apt-get install -y php${VER} php${VER}-fpm php${VER}-mysql \ php${VER}-curl php${VER}-gd php${VER}-mbstring php${VER}-xml \ php${VER}-zip php${VER}-bcmath php${VER}-cli systemctl enable --now php${VER}-fpm done
⚙️

Panel & Service Issues

Panel not loading or service crashes

Panel URL not opening — browser shows "Connection Refused"

Panel Down

Root Cause

  • ▸NexaPanel service stopped unexpectedly
  • ▸Browser using wrong port number
  • ▸Firewall blocking the panel port
1

Check service status

bash
systemctl status nexapanel
2

Start or restart the panel service

bash
systemctl restart nexapanel && systemctl enable nexapanel
3

Find which port panel is listening on

bash
grep 'PORT' /opt/nexapanel/.env
4

Allow port through firewall

bash
# UFW (Ubuntu/Debian): ufw allow 8090/tcp # firewalld (CentOS/AlmaLinux): firewall-cmd --permanent --add-port=8090/tcp && firewall-cmd --reload
5

Check recent panel logs

bash
journalctl -u nexapanel -n 60 --no-pager

Panel service won't start — shows "Active: failed (Result: exit-code)"

Service Crash

Root Cause

  • ▸Node.js version incompatible with panel bundle
  • ▸Bundle files corrupted or missing
  • ▸Another process is using the same port
1

View detailed crash reason

bash
journalctl -u nexapanel -n 100 --no-pager
2

Check if port is already occupied

bash
ss -tlnp | grep 8090
3

Run auto-repair to rebuild panel from scratch

bash
bash <(curl -fsSL https://nexapanel.hostganga.com/repair.sh)

Panel API returns 502 Bad Gateway

502 Error

Root Cause

  • ▸NexaPanel Node.js process is not running
  • ▸Service still starting up (wait 10 seconds)
  • ▸Nginx proxy_pass pointing to wrong port
1

Restart panel and test health endpoint

bash
systemctl restart nexapanel && sleep 8 curl -sf http://127.0.0.1:8090/api/panel/healthz && echo OK
2

Verify nginx proxy_pass port matches panel port

bash
grep proxy_pass /etc/nginx/sites-enabled/* /etc/nginx/conf.d/* 2>/dev/null

Login page loads but login button does nothing

Auth Issue

Root Cause

  • ▸PostgreSQL database connection lost
  • ▸Session secret not set in environment
  • ▸Browser blocking the login request (check console)
1

Test database connectivity

bash
PGPASSWORD=$(grep DB_PASS /opt/nexapanel/.env | cut -d= -f2 | tr -d '"') \ psql -h 127.0.0.1 -U nexapanel -d nexapanel -c 'SELECT 1;'
2

Restart services

bash
systemctl restart nexapanel postgresql
🌐

Nginx / Apache Issues

Web server config and startup problems

Nginx fails to start — "Failed to start nginx.service"

Nginx Error

Root Cause

  • ▸Configuration syntax error in a site config file
  • ▸Port 80 or 443 already occupied by another process
  • ▸A required module is missing
1

Test nginx configuration for syntax errors

bash
nginx -t
2

Find what is using port 80

bash
ss -tlnp | grep ':80'
3

Fix config and reload nginx

bash
nginx -t && systemctl restart nginx
4

View detailed nginx error log

bash
journalctl -u nginx -n 80 --no-pager tail -40 /var/log/nginx/error.log

Website returns 404 Not Found or shows a blank page

Site 404

Root Cause

  • ▸Nginx site config file is missing or disabled
  • ▸Document root path in config does not match actual folder
  • ▸PHP-FPM service not running for the selected PHP version
1

List active nginx site configs

bash
ls -la /etc/nginx/sites-enabled/ # RHEL/CentOS: ls /etc/nginx/conf.d/
2

Test config and reload nginx

bash
nginx -t && nginx -s reload
3

Check and restart PHP-FPM

bash
systemctl status php8.3-fpm systemctl restart php8.3-fpm

HTTP not redirecting to HTTPS

HTTPS Redirect

Root Cause

  • ▸Certbot did not add the redirect rule
  • ▸The "return 301" directive is missing from the port 80 server block
1

Add HTTP to HTTPS redirect in site config

bash
# Edit your site config: nano /etc/nginx/sites-available/yourdomain.com # Add inside the server { listen 80; } block: return 301 https://$host$request_uri;
2

Test and reload

bash
nginx -t && systemctl reload nginx
🐘

PHP Issues

PHP-FPM socket and version problems

PHP-FPM socket not found — "connect() to unix:/run/php/phpX.X-fpm.sock failed"

PHP FPM Socket

Root Cause

  • ▸PHP-FPM service for that PHP version is not running
  • ▸Socket path in nginx config doesn't match installed version
1

Restart PHP-FPM for the required version (replace X.X)

bash
# Example for PHP 8.3: systemctl restart php8.3-fpm systemctl enable php8.3-fpm # Confirm socket exists: ls -la /run/php/php8.3-fpm.sock
2

Check which PHP-FPM versions are running

bash
systemctl list-units 'php*-fpm' --no-pager

Website breaks after switching PHP version in panel

PHP Switch

Root Cause

  • ▸Old PHP-FPM socket path still referenced in nginx config
  • ▸New PHP-FPM version service not running yet
1

Start the target PHP version FPM service

bash
# Replace X.X with your target version: systemctl enable --now phpX.X-fpm
2

Reload nginx to apply new socket path

bash
nginx -t && nginx -s reload
3

Verify the socket path in site config

bash
grep fastcgi_pass /etc/nginx/sites-enabled/yourdomain.com
🗄️

Database Problems

PostgreSQL and MariaDB errors

PostgreSQL connection refused — panel cannot reach database

DB Connection

Root Cause

  • ▸PostgreSQL service is stopped
  • ▸Wrong host, port, or password in /opt/nexapanel/.env
  • ▸pg_hba.conf blocking local connections
1

Check and restart PostgreSQL

bash
systemctl status postgresql && systemctl restart postgresql
2

Test connection using credentials from .env

bash
PGPASSWORD=$(grep DB_PASS /opt/nexapanel/.env | cut -d= -f2 | tr -d '"') \ psql -h 127.0.0.1 -U nexapanel -d nexapanel -c 'SELECT version();'
3

Run the PostgreSQL auto-fix script

bash
bash <(curl -fsSL https://nexapanel.hostganga.com/pg-fix.sh)

MariaDB / MySQL — "Access denied for user"

MariaDB Error

Root Cause

  • ▸Root password changed or reset
  • ▸User privileges were accidentally revoked
1

Reset MariaDB root password

bash
systemctl stop mariadb mysqld_safe --skip-grant-tables & sleep 3 mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewPass123'; FLUSH PRIVILEGES;" killall mysqld_safe && systemctl start mariadb
2

Check what password panel uses

bash
grep -i 'MYSQL\|MARIADB\|DB_' /opt/nexapanel/.env

phpMyAdmin returns 404 or 502

phpMyAdmin

Root Cause

  • ▸phpMyAdmin not installed at expected path
  • ▸Nginx config block for /phpmyadmin is missing
1

Verify phpMyAdmin installation

bash
ls -la /var/www/phpmyadmin/index.php
2

Check nginx config for phpMyAdmin block

bash
grep -r phpmyadmin /etc/nginx/sites-enabled/ /etc/nginx/conf.d/ 2>/dev/null
3

Re-install via repair script

bash
bash <(curl -fsSL https://nexapanel.hostganga.com/repair.sh)
🔑

License Issues

Activation and validation problems

Trial license expired — panel shows "License Expired"

Expired

Root Cause

  • ▸The 15-day demo period has ended
1

Request a new demo license

Visit nexapanel.hostganga.com/demo.php to get a fresh 15-day license, or purchase a paid plan for unlimited access.

2

Enter the new key in panel

Panel → Settings → License → Enter Key → Activate

"Invalid license" or "IP mismatch" error

License Invalid

Root Cause

  • ▸Server IP changed (VPS was migrated or reinstalled)
  • ▸License server temporarily unreachable
  • ▸Key format is incorrect
1

Check your current server IP

bash
curl -sf https://api.ipify.org && echo
2

Activate the license via panel

Panel → Settings → License → Enter the key → click Activate

3

Get a new demo key for the new IP

nexapanel.hostganga.com/demo.php — enter your current server IP to get a new key.

4

Force a license refresh

bash
PANEL_PORT=$(grep '^PORT=' /opt/nexapanel/.env | cut -d= -f2 | tr -d '"') curl -sf "http://127.0.0.1:${PANEL_PORT}/api/panel/license"

License validation cron job is failing

Cron Issue

Root Cause

  • ▸Panel service is down when the cron fires
  • ▸Wrong port configured in the cron file
1

Inspect the system cron file

bash
cat /etc/cron.d/nexapanel-system
2

Test license endpoint manually

bash
PANEL_PORT=$(grep '^PORT=' /opt/nexapanel/.env | cut -d= -f2 | tr -d '"') curl -sf "http://127.0.0.1:${PANEL_PORT}/api/panel/license"
3

View the cron log

bash
tail -60 /var/log/nexapanel-cron/license.log 2>/dev/null || echo 'No log file yet'
🔒

SSL / HTTPS Issues

Certificate generation and renewal problems

SSL certificate generation fails — Certbot returns an error

SSL Error

Root Cause

  • ▸Domain DNS not yet pointing to this server IP
  • ▸Port 80 is blocked by firewall (needed for ACME challenge)
  • ▸Rate limit reached: 5 certificates per domain per week
1

Verify DNS resolution for your domain

bash
dig +short yourdomain.com # Result should be your server IP
2

Confirm port 80 is accessible from outside

bash
curl -I http://yourdomain.com ufw status | grep 80
3

Run Certbot manually

bash
certbot --nginx -d yourdomain.com -d www.yourdomain.com \ --non-interactive --agree-tos -m admin@yourdomain.com
4

If rate-limited, test with staging server first

bash
certbot --nginx -d yourdomain.com --staging

SSL certificate is not auto-renewing

Auto-Renew

Root Cause

  • ▸Certbot cron job missing or disabled
  • ▸Nginx reload hook failing after renewal
1

Test renewal in dry-run mode

bash
certbot renew --dry-run
2

Check certbot cron entry

bash
cat /etc/cron.d/nexapanel-system | grep certbot
3

Force renew a specific domain certificate

bash
certbot certonly --force-renew --nginx -d yourdomain.com
📧

Email Issues

Postfix and Dovecot mail problems

Emails are not being sent — Postfix error

Mail Send

Root Cause

  • ▸Postfix service is stopped
  • ▸Port 25 is blocked by your datacenter (common with cloud VPS)
  • ▸DKIM/SPF not configured causes spam rejection
1

Check Postfix service status

bash
systemctl status postfix && postfix check
2

Send a test email from command line

bash
echo 'Test from NexaPanel' | mail -s 'Test Email' your@email.com
3

Check the mail queue for stuck messages

bash
mailq && postqueue -p
4

Read recent mail logs

bash
tail -100 /var/log/mail.log
5

Restart mail services

bash
systemctl restart postfix dovecot

Cannot receive emails — Dovecot IMAP error

IMAP Error

Root Cause

  • ▸Dovecot service not running
  • ▸Ports 143 (IMAP) and 993 (IMAPS) blocked by firewall
1

Check Dovecot status

bash
systemctl status dovecot
2

Open IMAP/IMAPS ports

bash
ufw allow 143/tcp && ufw allow 993/tcp && ufw allow 587/tcp
3

View Dovecot error log

bash
tail -60 /var/log/dovecot.log 2>/dev/null || journalctl -u dovecot -n 60
⚡

Node.js / PM2 Issues

Application process management problems

Node.js app not starting in PM2

PM2 Error

Root Cause

  • ▸Application crashes at startup (check logs for stack trace)
  • ▸Wrong entry file path in pm2 start command
  • ▸Port already used by another process
  • ▸Node.js version mismatch
1

Check PM2 status and recent logs

bash
pm2 status && pm2 logs --lines 80
2

Run app directly to see the error

bash
node /path/to/your/app.js
3

Restart all PM2 managed processes

bash
pm2 restart all && pm2 save
4

Reinstall PM2 systemd startup hook

bash
pm2 startup systemd -u root && pm2 save

"pm2: command not found"

PM2 Missing

Root Cause

  • ▸PM2 not installed globally
  • ▸Node.js PATH not set correctly
1

Install PM2 globally and configure startup

bash
npm install -g pm2 && pm2 startup systemd -u root && pm2 save
📁

FTP Issues

FTP account connection problems

FTP connection refused or "530 Login incorrect"

FTP Error

Root Cause

  • ▸vsftpd/ProFTPD service not installed or stopped
  • ▸Port 21 blocked by firewall
  • ▸Wrong FTP username or password
1

Check FTP service status

bash
systemctl status vsftpd 2>/dev/null || systemctl status proftpd 2>/dev/null
2

Open required FTP ports

bash
ufw allow 21/tcp && ufw allow 20/tcp ufw allow 40000:50000/tcp
3

Restart the FTP service

bash
systemctl restart vsftpd 2>/dev/null || systemctl restart proftpd 2>/dev/null
💾

Files & Disk Issues

File permissions and disk space problems

"Permission denied" in the file manager

Permission Error

Root Cause

  • ▸Web root files owned by wrong user (e.g. root instead of www-data)
  • ▸File/directory permissions too restrictive
1

Fix ownership and permissions for a domain

bash
# Replace yourdomain.com with your actual domain: chown -R www-data:www-data /var/www/yourdomain.com find /var/www/yourdomain.com -type d -exec chmod 755 {} \; find /var/www/yourdomain.com -type f -exec chmod 644 {} \;

Disk full — "No space left on device"

Disk Full

Root Cause

  • ▸Log files grown too large
  • ▸Old backup archives not cleaned up
  • ▸Upload directory filled with large files
1

Check disk usage by directory

bash
df -h / du -sh /* 2>/dev/null | sort -rh | head -20
2

Clean apt cache and old packages

bash
apt-get clean && apt-get autoremove -y
3

Find files larger than 100 MB

bash
find / -size +100M -not -path '/proc/*' -not -path '/sys/*' 2>/dev/null | sort
4

Compress and truncate old system logs

bash
journalctl --vacuum-size=100M truncate -s 0 /var/log/syslog 2>/dev/null find /var/log -name '*.gz' -mtime +30 -delete
🛡️

Security & Firewall

UFW, Fail2ban, and access control issues

Your IP is blocked — cannot access SSH or panel

IP Blocked

Root Cause

  • ▸Fail2ban triggered after too many failed SSH/panel login attempts
  • ▸UFW rule accidentally blocking your IP
1

From VPS console or another IP — unban your IP

bash
# Fail2ban: fail2ban-client unban YOUR.IP.ADDRESS # UFW: ufw delete deny from YOUR.IP.ADDRESS ufw allow from YOUR.IP.ADDRESS to any port 22
2

See who is currently banned

bash
fail2ban-client status sshd ufw status | grep DENY

Firewall is blocking all traffic — server unreachable

Firewall Lock

Root Cause

  • ▸UFW accidentally set to deny all incoming before SSH rule was added
  • ▸All custom rules were flushed accidentally
1

From VPS rescue console — disable and reset UFW

bash
ufw --force disable ufw --force reset ufw default allow incoming && ufw default allow outgoing ufw enable
2

Then set the correct production rules

bash
ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp ufw allow 8090/tcp ufw default deny incoming ufw reload ufw status verbose
🔧

Problem still not solved?

Run the repair script — it diagnoses and fixes most issues automatically.

bash <(curl -fsSL https://nexapanel.hostganga.com/repair.sh)
🚀

Need a fresh install?

Supports Ubuntu 20.04/22.04/24.04, Debian 11/12, AlmaLinux, Rocky Linux.

bash <(curl -fsSL https://nexapanel.hostganga.com/install.sh)