6. Troubleshooting — Common Issues & Solutions

[admin]

If something isn't working as expected, you're in the right place. This guide covers the most common issues you may encounter with Panelica and how to resolve them.

1. Installation Issues​

Problem: "curl: command not found"
Solution: Install curl first:

apt update && apt install -y curl

Problem: "Permission denied" or "must be run as root"
Solution: You need root access. Switch to a root shell by running sudo -i or sudo su - (either works), then run the installer again.

Problem: Installer fails at dependency installation
Solution: Run these commands to clear package locks:

pkill -9 unattended-upgrade
dpkg --configure -a
apt update

Then run the installer again.

Problem: "Not enough disk space"
Solution: The installer needs at least 15 GB free on /opt. Check with df -h /opt. Free up space or resize your disk.

Problem: "Not enough RAM"
Solution: Minimum 1 GB RAM required. Check with free -h. If using a cloud VPS, upgrade to a larger plan. See Server Requirements for full details.

Problem: Installer hangs at "Starting services"
Solution: Wait up to 2 minutes — some services take time to initialize. If still hanging, check logs:

tail -50 /tmp/panelica-install.log
pn-service status all

---

2. Panel Access Issues​

Problem: Cannot access panel at https://ip:8443
Check these in order:

1. Verify backend is running: pn-service status backend
2. Verify nginx-panel is running: pn-service status nginx-panel
3. Check your cloud provider's firewall allows port 8443 inbound (AWS Security Groups, Hetzner Firewall, DigitalOcean Firewall, etc.)
4. Check the local firewall: nft list ruleset | grep 8443
5. Try restarting both services: pn-service restart nginx-panel && pn-service restart backend

Problem: "Connection refused" on port 8443
Solution: The backend or nginx-panel service is likely not running.

pn-service status backend
pn-service status nginx-panel

# If stopped, start them:
pn-service start backend
pn-service start nginx-panel

Problem: Browser shows SSL certificate error
Solution: This is normal with the default self-signed certificate. Click "Advanced" then "Proceed" (or "Accept the Risk") in your browser. To fix this permanently, set up your own domain pointing to the server and issue a Let's Encrypt certificate.

Problem: Forgot root password
Solution: Use SSH to reset via the Panelica CLI:

panelica user reset-password --username root --password YourNewPassword
pn-service restart backend

Problem: Panel loads but shows blank white page
Solution: Frontend files may be missing or corrupted. Rebuild them:

cd /opt/panelica/ServerPanel && npm run build
cp -r build/* /opt/panelica/var/www/panel/
pn-service restart nginx-panel

---

3. Domain & Website Issues​

Problem: Domain shows 403 Forbidden
Solutions:

• Check the document root exists and contains an index file (index.html or index.php)
• Check file permissions — files should be 644, directories should be 755
• For Laravel/Symfony apps: the document root must point to public_html/public, not just public_html

Problem: Domain shows 502 Bad Gateway
Solution: The PHP-FPM pool is not running for this user or PHP version.

# Check which PHP version the domain uses (visible in the panel under Domain Edit > PHP):
pn-service status php

# Restart PHP-FPM for the specific user:
systemctl restart [email protected]

Replace 8.4 with the PHP version your domain uses and username with the system username.

Problem: Domain shows 500 Internal Server Error
Solutions:

• Check the PHP error log: /opt/panelica/var/logs/php/
• Check the nginx error log: /opt/panelica/var/logs/nginx-customer/error.log
• Common causes: missing PHP extensions, incorrect .htaccess rules, or application configuration errors

Problem: Website works but is very slow
Solutions:

• Enable OPcache (usually enabled by default — verify in Domain Edit > PHP > Extensions)
• Check PHP memory_limit and increase from 128M to 256M or higher if needed
• Check if disk I/O is the bottleneck: iostat -x 1 5
• Check resource usage in the panel dashboard for CPU/RAM spikes

---

4. DNS Issues​

Problem: Domain not resolving after changing nameservers
Solution: DNS propagation can take up to 48 hours. Check the current status from an external resolver:

dig +short yourdomain.com @8.8.8.8
nslookup yourdomain.com 8.8.8.8

If it still shows the old IP after 48 hours, double-check your nameserver settings at your domain registrar.

Problem: DNS records not updating
Solution: Check that BIND is running and the zone file is syntactically valid:

pn-service status bind

# Check zone syntax:
named-checkzone yourdomain.com /opt/panelica/var/dns/zones/yourdomain.com.zone

Problem: Subdomains not working
Solution: Verify the subdomain has an A record pointing to your server's IP address. Check in the panel under Domains > DNS Management. If using Cloudflare, make sure the subdomain record exists there as well.

---

5. SSL / HTTPS Issues​

Problem: Let's Encrypt certificate not issuing
Most common causes:

• The domain's A record doesn't point to this server yet — check with dig +short yourdomain.com
• Port 80 is blocked — Let's Encrypt requires the HTTP-01 challenge on port 80
• Rate limited — Let's Encrypt allows 5 duplicate certificates per domain per week
• Check the backend log for ACME errors: /opt/panelica/var/logs/backend/backend.log and search for "acme" or "ssl"

Problem: Certificate expired and not auto-renewed
Solution: Trigger a manual renewal from Domain Edit > SSL tab > Renew Certificate. Also restart the backend to ensure the auto-renewal scheduler is active:

pn-service restart backend

---

6. Email Issues​

Problem: Cannot send emails
Solutions:

• Verify Postfix is running: pn-service status postfix
• Check if port 25 is blocked by your cloud provider (many providers block outbound port 25 by default — you may need to request it to be unblocked)
• Check the mail log for errors: /opt/panelica/var/logs/mail/mail.log

Problem: Emails going to spam
Solutions — make sure all of these are configured:

• PTR record (reverse DNS): Set up with your hosting provider — must match your mail hostname (e.g., mail.yourdomain.com)
• SPF record: Verify it exists: dig +short TXT yourdomain.com — should contain v=spf1 ... -all
• DKIM signing: Check outgoing mail headers for a DKIM-Signature header
• DMARC record: Verify it exists: dig +short TXT _dmarc.yourdomain.com

All four (PTR + SPF + DKIM + DMARC) are required for reliable inbox delivery, especially with Gmail and Outlook.

Problem: Cannot receive emails
Solutions:

• Verify Dovecot is running: pn-service status dovecot
• Check the MX record: dig +short MX yourdomain.com — it should point to your mail server
• Port 25 must be open inbound for receiving mail

Problem: Roundcube webmail not loading
Solution: Roundcube runs behind Apache. Check and restart:

pn-service status apache
pn-service status nginx-customer

# Restart if needed:
pn-service restart apache

---

7. Database Issues​

Problem: MySQL not starting
Solution:

# Check MySQL status and logs:
pn-service status mysql
tail -50 /opt/panelica/var/logs/mysql/error.log

# Common fix — check if disk is full:
df -h /opt/panelica/var/db/mysql/

Problem: PostgreSQL not starting
Solution:

pn-service status postgresql
tail -50 /opt/panelica/var/logs/postgresql/postgresql.log

Problem: Cannot connect to phpMyAdmin
Solution: phpMyAdmin runs on Apache (port 7081) behind the nginx proxy. Check:

pn-service status apache
pn-service restart apache

---

8. PHP Issues​

Problem: "Call to undefined function" errors
Solution: A required PHP extension is not enabled. Enable it from Domain Edit > PHP > Extensions in the panel. To check currently loaded extensions via CLI:

/opt/panelica/services/php/8.4/bin/php -m

Replace 8.4 with your PHP version.

Problem: File upload fails or "upload_max_filesize" error
Solution: Increase PHP limits in Domain Edit > PHP > php.ini Editor:

upload_max_filesize = 256M
post_max_size = 256M
max_execution_time = 300

Save and the PHP-FPM pool restarts automatically.

Problem: PHP-FPM not starting for a user
Solution: Check the service status and config syntax:

# Check service status:
systemctl status [email protected]

# Check config syntax:
/opt/panelica/services/php/8.4/sbin/php-fpm -t -y /opt/panelica/etc/php-fpm-users/username/8.4/pool.d/username.conf

Replace username and 8.4 as appropriate.

---

9. Service Management​

Problem: A service won't start
Solution: Check the status and system journal for detailed error messages:

# Check status:
pn-service status SERVICE_NAME

# View detailed logs:
journalctl -u panelica-SERVICE_NAME --no-pager -n 50

Replace SERVICE_NAME with the actual service name (e.g., backend, nginx-customer, mysql, postgresql).

Problem: All services stopped after reboot
Solution: Services are configured to auto-start on boot. If they did not start:

pn-service start all

If this is a recurring problem, verify systemd unit files are enabled:

systemctl is-enabled panelica-backend panelica-nginx-panel panelica-nginx-customer

---

10. General Diagnostic Commands​

Quick reference for the most useful diagnostic commands:

Check	Command
All service status	pn-service status all
Backend log	tail -f /opt/panelica/var/logs/backend/backend.log
Nginx error log	tail -f /opt/panelica/var/logs/nginx-customer/error.log
Mail log	tail -f /opt/panelica/var/logs/mail/mail.log
MySQL error log	tail -f /opt/panelica/var/logs/mysql/error.log
PHP error log	tail -f /opt/panelica/var/logs/php/php_errors.log
Disk usage	df -h /opt
RAM usage	free -h
Panelica version	panelica version
OS version	cat /etc/os-release

---

Related Guides​

• Server Requirements — minimum hardware and OS requirements
• Installation Guide — step-by-step installation instructions
• Setup Wizard — first-time configuration walkthrough
• First Steps After Setup — what to do after installation
• FAQ — frequently asked questions

---

Still stuck? Post in Bug Reports with your Panelica version, OS version, and relevant log output.