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

Check the Nginx service status and restart:

# Check Nginx service status
systemctl status nginx

# Restart Nginx (or use Centmin Mod's cmservice shortcut)
systemctl restart nginx
# or
cmservice nginx restart

Permission denied errors for website files in Centmin Mod are caused by incorrect file ownership or wrong file permissions. Centmin Mod uses the nginx user and group for web file ownership.

Correct permissions for Centmin Mod web files:

• Directories: 755 (owner read/write/execute, group and others read/execute)
• Files: 644 (owner read/write, group and others read-only)
• Ownership: nginx:nginx (the nginx user owns all web files)

Fix file ownership and permissions:

# Fix ownership to nginx user
chown -R nginx:nginx /home/nginx/domains/yourdomain.com/public

# Fix directory permissions to 755
find /home/nginx/domains/yourdomain.com/public -type d -exec chmod 755 {} \;

# Fix file permissions to 644
find /home/nginx/domains/yourdomain.com/public -type f -exec chmod 644 {} \;

If the issue persists, check for SELinux denials with sestatus and review /var/log/audit/audit.log for AVC denials.

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.

WordPress-specific 403 errors are usually caused by Centmin Mod’s tools/autoprotect.sh security tool, which blocks access to wp-login.php and xmlrpc.php by default to prevent brute force attacks.

Bypassing autoprotect for a specific vhost

# Create a bypass file in the domain's public directory
touch /home/nginx/domains/yourdomain.com/public/.autoprotect-bypass

# Re-run autoprotect to apply the bypass
/usr/local/src/centminmod/tools/autoprotect.sh

Alternative: VHOSTCTRL_AUTOPROTECTINC variable

Set VHOSTCTRL_AUTOPROTECTINC in /etc/centminmod/custom_config.inc to control autoprotect behavior globally.

Check file ownership

WordPress files must be owned by the nginx user and group:

# Fix ownership recursively
chown -R nginx:nginx /home/nginx/domains/yourdomain.com/public

# Verify
ls -la /home/nginx/domains/yourdomain.com/public/wp-login.php

For more details, see the forum discussion. Also see WordPress Auto-Installer.

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)
• Wrong version number at the prompt — When menu option 4 asks for the Nginx version, enter only the version number (e.g., 1.27.4). To set a persistent custom version, add NGINX_VERSION='1.27.4' in /etc/centminmod/custom_config.inc
• Third-party module incompatibility — Custom modules compiled for an older Nginx version may fail with a newer version. Check nginx -V output for the modules list and test each one
• Missing development libraries may need to be installed — check if gcc, make, and pcre-devel are installed

Before and after validation

# Before upgrading: verify current Nginx works
nginx -t

# After upgrading: validate config before restart
nginx -t && ngrestart

# Check compile flags and modules
nginx -V

For more details, see the forum discussion.

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'
• PECL extension compile failures — Extensions installed via PECL must be rebuilt after a PHP major/minor version upgrade. Check loaded modules with php -m and verify each extension’s .so file exists in the new extension directory
• Force full extension rebuild — Set AUTODETECPHP_OVERRIDE='y' in /etc/centminmod/custom_config.inc to force Centmin Mod to reinstall all PHP extensions even on minor version upgrades

Post-upgrade verification

# Verify PHP version
php -v

# Check loaded extensions
php -m

# Check PHP configuration files
php --ini

# Test PHP-FPM config
php-fpm -t

For more details, see the forum discussion.

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 AlmaLinux 8/9/10, Rocky Linux 8/9/10, or CentOS 7 (EOL)
• 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

Diagnosing installation failures

Check the install logs at /root/centminlogs/. Install log filenames follow the pattern centminmod_YYYYMMDD-HHMMSS_install.log.

# List install logs (newest first)
ls -lhrt /root/centminlogs/centminmod_*_install*.log

# Check last 100 lines of most recent install log
tail -100 /root/centminlogs/$(ls -t /root/centminlogs/centminmod_*_install*.log | head -1)

Common causes and fixes

• YUM/DNF repository failures — Repos may be temporarily unavailable. Wait and retry, or check yum repolist for broken repos. CentOS 7 vault repos may have mirror issues.
• Network/DNS timeouts — Verify DNS resolution: dig google.com. Check connectivity: curl -I https://github.com. Firewall rules or cloud provider security groups may block outbound connections.
• Insufficient disk space — Centmin Mod needs at least 10GB free. Check with df -hT. Compilation alone may need 3-5GB of temporary space.
• Missing or low swap — Low-RAM VPS (1GB) requires swap. Verify: free -m. If swap is 0, create a swap file before retrying the install.
• SELinux interference — SELinux in enforcing mode can block compiler operations. Check: sestatus. Centmin Mod sets SELinux to permissive during install, but pre-existing policies may interfere.
• Firewall blocking outbound — If iptables or cloud security groups restrict outbound traffic, the installer cannot download source tarballs and RPM packages.

For more details, see the forum discussion.

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

Unlike high load with low CPU (I/O-bound above), high CPU load means processes are actively consuming CPU cycles. Common causes on LEMP stacks:

Step 1: Identify the process

# Real-time process view sorted by CPU
top -c

# Or use htop for a better interface
htop

# Historical CPU data (if sysstat/sar is installed)
sar -u 1 10

# Per-second stats including CPU, disk, network
dstat -cdngy 1 10

Step 2: Diagnose by process type

• PHP-FPM worker storms — Too many PHP-FPM child processes consuming CPU. Check pm.max_children in /usr/local/etc/php-fpm.d/www.conf. Enable the slow log to find long-running PHP scripts: set request_slowlog_timeout = 5s and check slowlog path in pool config
• MySQL slow queries — Enable the slow query log in /etc/my.cnf: slow_query_log = 1, long_query_time = 1. Review with mysqldumpslow /var/lib/mysql/slow.log
• OPcache misconfiguration — If opcache.max_accelerated_files is too low, PHP constantly recompiles scripts. Increase it and set opcache.memory_consumption appropriately. See PHP-FPM Optimization

Step 3: Apply tuning

Run tools/hptweaks.sh for kernel and memory tuning recommendations including transparent huge pages and jemalloc memory allocator settings.

For more details, see the forum discussion.

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

Centmin Mod includes a disk space alert script at /etc/cron.daily/diskalert that runs daily and emails you when disk usage exceeds a configured threshold.

To configure it:

• Edit /etc/cron.daily/diskalert and set the EMAIL='' field to your email address
• Set the threshold percentage with DISKSPACE_ALERTPERCENTAGE='80' (alerts when usage exceeds 80%)
• Adjust the percentage as needed for your server’s storage capacity

For more details, see the forum discussion.

Centmin Mod performs checks on SSH login (yum/dnf update checks, Nginx version check), which can be slow if the server has IPv6 connectivity issues causing DNS or HTTP timeouts.

Diagnose the issue:

Run the following command to test for IPv6 timeouts:

curl -Iv https://nginx.org/en/download.html

If this command hangs or is slow, IPv6 is likely the cause.

Fix — Disable IPv6:

• Add net.ipv6.conf.all.disable_ipv6 = 1 to /etc/sysctl.conf and apply with sysctl -p
• Or set DISABLE_IPVSIX='y' in /etc/centminmod/custom_config.inc and run a Centmin Mod update to apply the setting

For more details, see the forum discussion.

If PHP-FPM is crashing with SIGSEGV (Signal 11) errors, you can enable debug mode to capture core dumps and generate gdb backtraces for diagnosis.

Step 1 — Enable debug mode:

Add the following to /etc/centminmod/custom_config.inc:

PHPDEBUGMODE='y'
AUTODETECPHP_OVERRIDE='y'

Step 2 — Recompile PHP:

Run centmin.sh menu option 5 to recompile PHP with debug symbols enabled.

Step 3 — Reproduce the crash and analyze:

After the crash occurs, core dump files are saved at /tmp/core-*. Run the gdb backtrace:

gdb -q $(which php-fpm) /tmp/core-FILE -ex 'thread apply all bt full' -ex quit

Replace /tmp/core-FILE with the actual core dump filename.

For more details, see the forum discussion.