Troubleshooting

Always test your Nginx configuration before restarting:

nginx -t

Common causes of startup failures:

• Syntax errors or typos in vhost configuration files under /usr/local/nginx/conf/conf.d/
• Missing or expired SSL certificate files referenced in vhost configs
• Conflicting server_name directives across multiple vhost files
• Port 80 or 443 already in use by another process (check with ss -tlnp | grep ':80\|:443')

Check the error log for details: /usr/local/nginx/logs/error.log

A 403 Forbidden error typically indicates one of these issues:

• File permissions — Web files should be readable by the Nginx user. Directories need 755 and files need 644 permissions.
• Missing index file — No index.html or index.php in the document root, and autoindex is off.
• SELinux — On CentOS/RHEL systems, SELinux may block Nginx from reading files. Check with sestatus and review audit logs.
• Deny rules — Check vhost config for deny all; directives that may be blocking access.

Verify the document root path is correct in your vhost file at /usr/local/nginx/conf/conf.d/yourdomain.com.conf.

If Nginx PageSpeed (ngx_pagespeed) is causing problems or unexpected behavior:

• Disable PageSpeed temporarily by setting pagespeed off; in the vhost config
• Clear the PageSpeed cache: rm -rf /var/ngx_pagespeed_cache/*
• Check if PageSpeed filters are conflicting with your site’s JavaScript or CSS
• Verify the PageSpeed module is compiled into Nginx: nginx -V 2>&1 | grep pagespeed

PageSpeed is an optional module. If not needed, rebuild Nginx without it via Centmin Mod menu option 4.

SSL/TLS issues commonly arise from:

• Expired certificates — Check certificate expiry with openssl x509 -enddate -noout -in /usr/local/nginx/conf/ssl/yourdomain.com/yourdomain.com.crt
• Let’s Encrypt renewal failures — Check /root/centminlogs/ for acme.sh related logs
• Wrong certificate paths — Verify ssl_certificate and ssl_certificate_key paths in vhost config
• DNS not pointing to server — Let’s Encrypt HTTP-01 validation requires the domain to resolve to your server IP

For Let’s Encrypt SSL, Centmin Mod uses acme.sh. Renew manually with: /root/.acme.sh/acme.sh --renew -d yourdomain.com

When Nginx upgrade or recompile via Centmin Mod menu option 4 fails:

• Check the compile log in /root/centminlogs/ for the most recent centminmod_*_nginx_*.log file
• Ensure you have sufficient disk space (df -h /) and memory (free -m)
• Missing development libraries may need to be installed — check if gcc, make, and pcre-devel are installed
• Third-party modules may be incompatible with the new Nginx version

Post your compile log on the community forums for help diagnosing the issue.

502 Bad Gateway usually means PHP-FPM is not running or has crashed:

systemctl status php-fpm
systemctl restart php-fpm

504 Gateway Timeout means PHP scripts are exceeding timeout values. Increase these settings:

• max_execution_time in /usr/local/lib/php.ini
• fastcgi_read_timeout in your Nginx vhost config
• request_terminate_timeout in PHP-FPM pool config at /usr/local/etc/php-fpm.d/www.conf

Check PHP-FPM error logs: /var/log/php-fpm/www-error.log

PHP-FPM child processes can consume significant memory. To reduce usage:

• Lower pm.max_children in /usr/local/etc/php-fpm.d/www.conf
• Switch from pm = static to pm = ondemand or pm = dynamic on low-memory VPS
• Set pm.max_requests to recycle workers after a set number of requests (e.g., 500)
• Disable unused PHP extensions to reduce per-process memory footprint

Check current memory per worker: ps --no-headers -o rss -C php-fpm | awk '{ sum+=$1 } END { print sum/NR/1024 " MB avg" }'

After a PHP version upgrade, some extensions may need to be recompiled:

• Check loaded extensions: php -m
• Verify the extension .so file exists in the extensions directory: php -i | grep extension_dir
• If the .so file is missing, recompile the extension or use Centmin Mod’s addons to reinstall it
• Check /usr/local/lib/php.ini for the correct extension= line

See PHP Extensions for the full list of bundled extensions.

If PHP upgrade/downgrade via Centmin Mod menu option 5 fails:

• Check the compile log in /root/centminlogs/ for errors
• Ensure adequate disk space and memory — PHP compilation requires at least 512MB of available RAM
• Some PHP versions may not be compatible with your OS version (e.g., very old PHP on EL9/EL10)
• Missing development libraries — run yum groupinstall 'Development Tools'

If PHP changes are not taking effect, Zend OPcache may be serving stale bytecode:

• Restart PHP-FPM to clear the OPcache: systemctl restart php-fpm
• For development, set opcache.validate_timestamps=1 and opcache.revalidate_freq=0 in php.ini
• If OPcache runs out of memory, increase opcache.memory_consumption (default is usually 128MB)

See Zend OPcache configuration for tuning details.

Check the MariaDB error log first:

cat /var/log/mysqld.log | tail -50
# or
journalctl -u mariadb --no-pager -n 50

Common causes:

• InnoDB log file size mismatch — If you changed innodb_log_file_size, you may need to remove old log files after a clean shutdown
• Corrupted InnoDB tablespace — Try starting with innodb_force_recovery=1 in /etc/my.cnf
• Disk space full — Check with df -h
• After MariaDB version upgrade — Run mysql_upgrade to update system tables

This error means all available MariaDB connections are in use:

• Increase max_connections in /etc/my.cnf (default is 150)
• Check for long-running queries: mysqladmin processlist
• Ensure your application is properly closing database connections
• Consider using persistent connections or a connection pooler if your application supports it

# Check current max and used connections
mysql -e "SHOW VARIABLES LIKE 'max_connections';"
mysql -e "SHOW STATUS LIKE 'Max_used_connections';"

Centmin Mod stores the MySQL root password during initial installation. Check:

cat /root/.my.cnf

If the password file is missing, you can reset the root password by starting MariaDB in safe mode:

systemctl stop mariadb
mysqld_safe --skip-grant-tables &
mysql -u root
# Then run:
# FLUSH PRIVILEGES;
# ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewPassword';
# Then restart normally:
systemctl restart mariadb

MariaDB memory usage is primarily controlled by the InnoDB buffer pool. For low-memory VPS:

• Reduce innodb_buffer_pool_size in /etc/my.cnf (set to 25–50% of available RAM)
• Lower tmp_table_size and max_heap_table_size
• Reduce key_buffer_size if not using MyISAM tables

See MySQL Management for detailed tuning guidance.

If the initial installation via the install command fails:

• Fresh OS only — Install on a fresh minimal OS installation without other control panels or web servers
• Supported OS — Ensure you are using CentOS 7, AlmaLinux 8/9/10, or Rocky Linux 8/9/10
• Minimum requirements — At least 1GB RAM (2GB recommended), 10GB disk space
• Network access — The installer needs to download packages from various repositories
• Root access — Must be run as root user, not via sudo

Check the installation log:

ls -lah /root/centminlogs/
# Review the most recent centminmod_*.log file

When running cmupdate or Centmin Mod menu option 23 for updates:

• Ensure git is installed and working: git --version
• Check if the /usr/local/src/centminmod directory has local modifications that conflict with the update
• Try a forced update: cd /usr/local/src/centminmod && git fetch && git reset --hard origin/master
• Network connectivity issues may prevent downloading from GitHub

Low disk space can cause failures across all LEMP components:

# Check disk usage
df -h

# Find large files
du -sh /var/log/* | sort -rh | head -20
du -sh /home/nginx/domains/*/log/* | sort -rh | head -20

• Rotate and compress old log files in /var/log/ and /home/nginx/domains/*/log/
• Clean up old Centmin Mod compile logs: ls -lah /root/centminlogs/
• Clear the YUM/DNF cache: yum clean all
• Check for large MariaDB binary logs: du -sh /var/lib/mysql/mysql-bin.*

High load average with low CPU usage typically indicates I/O wait:

• Check I/O wait with top or vmstat 1 5 (look at the wa column)
• Identify I/O-heavy processes: iotop -oa
• Slow disks on shared VPS hosting can cause this — consider upgrading to SSD/NVMe VPS
• MariaDB InnoDB buffer pool may be too small, causing excessive disk reads
• Nginx access/error logs being written to a slow disk

If YUM/DNF commands fail with package conflicts or repository errors:

• Clean the YUM cache: yum clean all && yum makecache
• Check for third-party repos that may conflict: yum repolist all
• Centmin Mod manages its own Nginx, PHP, and MariaDB — do not install these from OS repos
• If EPEL or Remi repos cause conflicts, temporarily disable them: yum --disablerepo=epel update

If you’re locked out after enabling CSF:

• Use your VPS provider’s console/VNC access to log into the server
• Temporarily disable CSF: csf -x
• Add your IP to the allow list before re-enabling: csf -a YOUR_IP_ADDRESS
• Re-enable CSF: csf -e

CSF’s Login Failure Daemon (LFD) may block legitimate users:

• Check if an IP is blocked: csf -g IP_ADDRESS
• Unblock an IP: csf -dr IP_ADDRESS (remove from deny) and csf -tr IP_ADDRESS (remove from temp deny)
• Increase LF_TRIGGER threshold in /etc/csf/csf.conf for less aggressive blocking
• Add trusted IPs or IP ranges to /etc/csf/csf.ignore to skip LFD monitoring

Restart CSF after changes: csf -r

CSF startup failures are often related to the underlying firewall backend:

• On EL8/EL9 systems, ensure iptables or iptables-nft packages are installed
• Disable firewalld if it conflicts: systemctl stop firewalld && systemctl disable firewalld
• Check that required ports are defined in /etc/csf/csf.conf under TCP_IN, TCP_OUT, UDP_IN, UDP_OUT
• Verify CSF passes its security check: perl /usr/local/csf/bin/csftest.pl

If you receive too many CSF/LFD alert emails:

• Disable specific alerts in /etc/csf/csf.conf:
  • Set LF_EMAIL_ALERT = 0 to disable blocked IP notifications
  • Set LF_PERMBLOCK_ALERT = 0 to disable permanent block alerts
• Increase block thresholds to reduce the frequency of blocks
• Use csf.pignore to ignore known-safe processes that trigger alerts