Official Technical Documentation & User Manual
Installation
Verified Guide • Updated 17 Oct 2026
Installation Verified Guide

Article #I-04: Comprehensive Installation Troubleshooting, Error Reference, SSL/Rewrite Fixes & Migration Rescue Guide

Updated 8 hours ago 6 min read 2 views
Installation Category · Part 4 of 4 Troubleshooting & Error Reference 404, DB, SSL, SMTP & PDF Fixes

Comprehensive Installation Troubleshooting, Error Reference, SSL/Rewrite Fixes & Migration Rescue Guide

Encountered an issue during or after installing Keystone X? This complete diagnostic reference explains how to read /error.log, how the Branded Error Shield works, and provides step-by-step fixes for every common server, database, URL rewrite, license validation, PDF logo, and SMTP email error.

1. How Keystone X Logs Errors (/error.log & SystemErrorHandler.php)

For security reasons, Keystone X never exposes raw PHP stack traces or SQL credentials to the browser (display_errors = 0). Instead, app/core/SystemErrorHandler.php intercepts every warning, exception, or fatal error and performs three actions automatically:

  1. Writes a Detailed Diagnostic Entry to /error.log: Open /error.log in your project root (or /app/error.log) to see the exact timestamp, Error Reference ID, PHP file and line number, HTTP request URI, authenticated user, and last executed SQL query with bound parameters.
  2. Displays the Branded Keystone X Error Shield: Shows a clean, reassuring screen to the user with the incident reference code.
  3. 1-Click Helpdesk Diagnostic Dispatch: Administrators can navigate to admin/settings#system and click Send System Diagnostics (admin/sendDiagnostics) to attach /error.log directly to a support ticket on the Keystone X Helpdesk!

2. Fixing 404 Page Not Found / Broken Clean URLs (.htaccess & Nginx)

Symptom: The home page or login screen loads at /, but clicking any link (like /user/login, /invoice/index, or /admin/settings) returns an Apache/Nginx 404 Not Found error.

Cause A: Hidden .htaccess File Was Not Uploaded

On macOS/Linux and in cPanel File Manager, files starting with a dot (.htaccess) are hidden by default. Enable Show Hidden Files (dotfiles) in cPanel File Manager and verify that .htaccess exists in your project root alongside index.php.

Cause B: Incorrect RewriteBase in a Subfolder

If your app URL is https://yourdomain.co.za/billing/, open .htaccess and change RewriteBase / to RewriteBase /billing/. Conversely, if your app is on a subdomain (https://billing.yourdomain.co.za/), ensure RewriteBase / is set.

Cause C: Apache mod_rewrite Disabled on a VPS

On a fresh Ubuntu/Debian VPS, enable mod_rewrite and set AllowOverride All in your Apache VirtualHost:

sudo a2enmod rewrite # Inside <Directory /var/www/...> set: AllowOverride All sudo systemctl restart apache2
Cause D: Running on Nginx (No .htaccess Support)

Add the following location blocks inside your Nginx server { ... } block:

location / { try_files $uri $uri/ /index.php?url=$uri&$args; } location ~ ^/(app|cache|backups|install)/ { deny all; return 403; }

3. Fixing Database Connection & SQL Strict Mode Errors

  • SQLSTATE[HY000] [2002] No such file or directory when DB_HOST is localhost: Change DB_HOST in app/config/config.php from 'localhost' to '127.0.0.1'. Using '127.0.0.1' tells PHP PDO to connect over standard TCP/IP port 3306 instead of looking for a missing Unix socket file (mysql.sock).
  • SQLSTATE[HY000] [1045] Access denied for user: On cPanel servers, remember that both your Database Name and Database Username are prefixed with your cPanel account name (e.g., cpaneluser_keystone, not just keystone). Also verify in cPanel → MySQL Databases that the user has been added to the database with ALL PRIVILEGES.
  • SQLSTATE[HY000] [2006] MySQL server has gone away during Large Backups or Imports: Increase max_allowed_packet = 64M and wait_timeout = 600 in your MySQL my.cnf / my.ini configuration.

4. Fixing License Server Connection & Lock Screen Issues

  • "Connection to the remote license server failed or invalid response":
    1. Verify that the php-curl extension is enabled on your server.
    2. Verify that your server can reach https://keystonex.co.za on outbound TCP port 443 (curl -I https://keystonex.co.za).
    3. On local Windows development environments (AMPPS / XAMPP / WampServer), if cURL fails with an SSL CA certificate error (cURL error 60: SSL certificate problem: unable to get local issuer certificate), download cacert.pem from https://curl.se/ca/cacert.pem and set curl.cainfo = "d:\AMPPS\php82\extras\ssl\cacert.pem" in your php.ini.
  • "Domain mismatch or license already bound to another installation": When migrating Keystone X from a staging URL to your live domain, log into your Licensing Portal at https://keystonex.co.za (or contact Keystone X Support) to reissue/rebind your domain fingerprint, then delete /cache/license.json so your server fetches a fresh token immediately.

5. Fixing Blank PDFs, Missing Logos & Outbound SMTP Failures

PDF & Company Logo Troubleshooting
  • Company Logo Not Showing on PDFs: Ensure the PHP gd extension is enabled (php -m | grep gd) and re-upload your logo as a standard PNG or JPG under admin/settings#branding. Keystone X uses get_pdf_logo_base64() to embed the image directly into the PDF stream so no external HTTP loopback request is required.
  • Corrupted or Blank PDF Downloads: Never add a closing ?> tag or trailing blank lines to app/config/config.php (index.php automatically heals config.php if a closing tag is detected). Also ensure memory_limit is at least 256M.
Outbound SMTP & Email Queue Troubleshooting
  • Emails Stuck in Pending inside EmailQueue/index: Ensure your scheduled Cron Job (cron_runner.php or cron.php) is active, or click Process Spool Batch Now in EmailQueue/index?mode=spool.
  • Emails Moving to Dead-Letter Queue (Failed): Open EmailQueue/index?mode=dead_letter and inspect the error_msg column. Common causes: using a normal account password instead of an App Password on Google Workspace / Microsoft 365 with 2FA enabled, or picking Port 465 with TLS instead of SSL (use Port 587 with TLS or Port 465 with SSL).
  • Master Kill-Switch Check: Verify under admin/settings#email that Disable Automated Outbound Emails (disable_automated_emails) is unchecked.

6. Quick-Reference Error Message Lookup Table

Exact Error Message Displayed Where It Originates Immediate Resolution
System Error: Configuration file not found and installation wizard is missing. index.php (Line 35) Neither app/config/config.php nor install/index.php exists. Restore app/config/config.php from backup or upload the /install folder to run the wizard.
Security Lockout: Login is not allowed until the /install directory is either deleted or renamed. UserController.php (Line 62) Click the red Yes, Delete /install Now button on the login screen, or delete/rename /install via cPanel File Manager.
license.key not found or not writable. AdminSettingsTrait.php (Line 486) Set permissions (chmod 755 or 775) on /app/config/ and chmod 644 (or 664) on /app/config/license.key and /cache/.
CRON_ERROR: Access Denied. Invalid or missing Security Key. cron.php (Line 174) When calling cron.php via HTTP/cURL, append ?key=YOUR_SECRET_KEY copied from admin/cron?mode=setup (or use cron_runner.php via CLI).
CRON_RUNNER ERROR: No active admin user found in database. cron_runner.php (Line 38) Ensure at least one user in the users table has role = 'admin'.
© 2026 Keystone X — Official Technical Documentation https://keystonex.co.za/docs/installation/article-i-04-comprehensive-installation-troubleshooting-error-reference-sslrewrite-fixes-migration-rescue-guide
Was this technical guide helpful?
Back to top