Why X-Cart Goes Blank or Returns 500

X-Cart 5 is a Doctrine-backed, heavily cached PHP application. A storefront that suddenly returns a bare HTTP 500 Internal Server Error or a completely white page rarely means the server itself failed. On a LiteSpeed/CloudLinux shared account, the web server is almost always healthy; what died is the PHP request. X-Cart wraps nearly everything in its service container and compiled cache, so a single malformed class, an out-of-memory condition, a PHP version mismatch, or a corrupted cache directory will halt the whole bootstrap before anything renders.

The blank screen specifically happens because production-grade PHP is configured with display_errors = Off. The fatal still occurs, but the message is suppressed and the browser receives an empty body or a generic 500. That behavior protects customers from seeing stack traces, but it also hides the one line of text you need. The entire diagnostic process is therefore about one thing: making the hidden error message visible, reading it, and acting on the specific class, file, and line it names.

X-Cart has three layers that can each throw. The PHP engine itself throws fatals (memory, syntax, missing extensions). The web server layer (LiteSpeed reading .htaccess) can throw 500s on an invalid directive. And X-Cart's own framework throws exceptions when the database, compiled cache, or a module is in an inconsistent state. Knowing which layer failed tells you which log to open, so start by identifying the layer before changing anything.

Locating the Right Logs Through Your Panel

There are three log sources available to an unprivileged hosting user, and they answer different questions.

The first is the per-domain PHP error_log. LiteSpeed writes PHP fatals into a file named error_log in the directory where the failing script lives. For a store installed in public_html, open cPanel File Manager, navigate to /home/USER/public_html/, enable Settings → Show Hidden Files, and look for error_log. Open it and read the last entries from the bottom. A typical fatal looks like PHP Fatal error: Allowed memory size of 134217728 bytes exhausted or PHP Fatal error: Uncaught Error: Class "..." not found in /home/USER/public_html/classes/...php:214. That file name and line number are the whole investigation. In DirectAdmin the path is identical; use the DirectAdmin File Manager with hidden files shown.

The second source is cPanel's Metrics → Errors screen (or DirectAdmin's System Info & Files → Error Log), which surfaces recent web-server-level 500s with the request URI. If this screen shows a 500 but the per-domain error_log is empty, the fault is usually in .htaccess rather than in PHP.

The third source is X-Cart's own log tree. The application keeps structured logs under /home/USER/public_html/var/log/. Files are dated, for example error.log.php and dated variants like php_errors.log.YYYY-MM-DD.php. These are the richest records of exceptions thrown inside the X-Cart framework, including Doctrine, template, and module failures. Each line begins with a <?php die(); ?> guard so the file cannot be read over HTTP; open it in File Manager's editor and scroll past that guard to the readable entries. When the storefront throws an application-level exception rather than a raw PHP fatal, this is where the full context lives.

Read all three in order: var/log/ first for X-Cart exceptions, the per-domain error_log next for raw PHP fatals, then the panel Errors screen for .htaccess problems. Match the timestamp of your failed page load to the log entry so you are reading the correct event and not an old one.

Turning On Visible Errors and X-Cart Debug Output

If the logs are empty or ambiguous, force the error to the surface for one controlled test. You can raise PHP visibility per directory without touching any server config by creating or editing .user.ini in public_html:

display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
memory_limit = 256M
max_execution_time = 120

LiteSpeed caches .user.ini values for up to 300 seconds, so wait five minutes or bump the PHP version in cPanel MultiPHP Manager to force a pool refresh, then reload the broken page. You will now see the actual fatal in the browser. Revert display_errors to Off the moment you have captured the message, because exposing stack traces on a live store leaks paths and credentials.

X-Cart also has a native developer mode that produces detailed exception pages with full stack traces instead of the generic error screen. Append the developer flag to a request, for example https://yourstore.com/admin.php?target=main&dev_mode=1, or open Admin area → My account / Settings → Environment and enable the development/debug option where your build exposes it. Developer mode disables aggressive template and container caching, which frequently makes a cache-corruption 500 vanish long enough to read the underlying cause. When you combine developer mode with the var/log/ entries, most exceptions name the exact module or class responsible.

One more facility matters: the compiled cache. A large share of post-update or post-module-change 500s come from a stale or half-written var/run/ cache. Using File Manager, rename /home/USER/public_html/var/run/ to var/run_old/ and then recreate an empty var/run/ folder with 0755 permissions. Load the storefront; X-Cart rebuilds the cache on the next request. If the site returns, the old cache was the fault and you can delete the renamed folder.

Resolving the Most Common 500 Triggers

Once the message is readable, the fix usually falls into one of five categories.

Memory exhaustion. A line reading Allowed memory size ... exhausted means the request ran out of RAM, common during cache rebuilds or import jobs. Raise memory_limit in .user.ini to 256M or 512M if your plan allows, and confirm the active value in cPanel Select PHP Version → Options.

PHP version mismatch. Errors like syntax error, unexpected '?' or a missing str_contains() indicate the PHP version is wrong for your X-Cart build. Set the correct version in MultiPHP Manager (cPanel) or PHP Selector (DirectAdmin/CloudLinux), typically PHP 7.4 or 8.1 depending on your X-Cart 5.4/5.5 release.

Missing extension. Class "PDO" not found or Call to undefined function mb_strlen() means an extension is disabled. Open PHP Selector / Select PHP Version and tick pdo, pdo_mysql, mbstring, gd, intl, curl, and openssl.

Broken module. If the stack trace names a path under classes/XLite/Module/, a third-party module is faulting. Disable it by editing var/run/classes/ is not advisable; instead rebuild the empty cache as above and, if it recurs, remove the module folder from /home/USER/public_html/modules/VENDOR/MODULE/ and clear var/run/ again.

Invalid .htaccess. If the panel Errors screen shows a 500 but PHP logs are clean, temporarily rename .htaccess to .htaccess.bak. If the site loads, a directive is incompatible with LiteSpeed; restore X-Cart's default rules from a clean copy rather than keeping edited ones. The same careful file-and-config discipline applies to any CMS move, as covered in our LiteCart migration and domain-change guide. After every fix, reload the page, confirm the var/log/ entry stops appearing, and set display_errors back to Off.