Troubleshooting & FAQs

Find authoritative solutions to common installation, environment, and runtime issues.

---

1. HTTP 500 Internal Server Error

An HTTP 500 status code indicates a fatal PHP or web server configuration error.

Checklist:

1. Inspect PHP Error Logs: Check storage/logs/error.log or your hosting web server error log.
2. Verify PHP Version: Ensure your server runs PHP 8.2.0 or higher. Running on PHP 8.1 or PHP 7.4 will trigger syntax or type incompatibility errors.
3. Verify PHP Extensions: Ensure pdo, pdo_mysql, mbstring, curl, json, fileinfo, openssl, and gd are enabled.
4. Inspect .htaccess: If your server does not have mod_rewrite enabled, comment out custom rewrite rules temporarily to isolate server directive errors.

---

2. HTTP 404 on Sub-pages & Admin Routes

If the homepage loads but visiting /admin or clean permalinks returns a 404 Not Found error, URL rewriting is not active on your web server.

Solutions:

• Apache: Confirm that mod_rewrite is enabled in your Apache configuration (a2enmod rewrite) and that the directory allows overrides:

  <Directory /var/www/html>
      AllowOverride All
  </Directory>

• Nginx: Ensure the try_files directive is present in your server block:

  try_files $uri $uri/ /index.php?$query_string;

---

3. Database Connection Failed

If the installer or CMS reports “Database connection failed”:

1. Verify that your database host is correct. On shared hosting, localhost or 127.0.0.1 is standard, while some providers require specific hostnames (e.g., mysql.yourdomain.com).
2. Verify that the user has been granted privileges on the database.
3. Ensure MySQL/MariaDB server is running and accessible on port 3306.
4. Check that PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8mb4" is supported.

---

4. File Permission Denied on Media Uploads

If uploading media fails with a permission error:

Ensure that storage/uploads/ is writable by the PHP process:

chmod -R 775 storage
chown -R www-data:www-data storage

On cPanel or 20i StackCP, ensure the directory permissions are set to 755 or 775.

---

5. License Activation Offline Fallback

If you attempt to activate a commercial license and your host cannot connect to the Central License Infrastructure:

1. Ensure the curl and openssl PHP extensions are enabled.
2. Check that outgoing HTTPS connections on port 443 are not blocked by a hosting firewall.
3. Remember: Core CMS operation is never blocked by licensing. Your live website and admin dashboard continue operating normally.