Why Zenphoto Fails Silently

Zenphoto sits on top of PHP and MySQL/MariaDB, and it reads and writes a large number of files during every page load: theme templates, plugin PHP, cached image derivatives, and the zp-data/zp-config.php configuration file. When any one of those pieces is unhappy, the visible symptom is usually one of three things: a completely blank page (the white screen of death), an HTTP 500 Internal Server Error page served by LiteSpeed, or a partially rendered gallery that stops mid-way. None of those messages tell you anything useful on their own, because production PHP is configured to hide error text from visitors so that file paths and database credentials never leak.

The blank page happens when PHP hits a fatal error but display_errors is off, so it stops execution and sends nothing. An HTTP 500 usually means the web server rejected something before PHP even finished: a malformed .htaccess directive, a PHP fatal error surfaced through the server, or a script that exceeded a resource limit like memory or execution time. On a Managed Cloud Shared Hosting account running LiteSpeed on CloudLinux, you cannot touch the server configuration, but you have everything you need to read the truth: the per-account error_log, Zenphoto's own debug facilities, the PHP Selector in cPanel or DirectAdmin, and File Manager. The work is almost always about finding the real message that PHP already wrote down, then acting on it.

The most common triggers on shared hosting are a PHP version mismatch after a MultiPHP change, a missing PHP extension that a plugin depends on (frequently gd, imagick, exif, or curl), a corrupted or outdated .htaccess, a memory ceiling hit while generating large image derivatives, and file permission problems inside zp-data/ or the album cache. Each of these leaves a distinct fingerprint in the logs, so reading them first saves hours of guessing.

Finding the Real Error Message

Start with the log that PHP writes automatically. On both cPanel and DirectAdmin, PHP appends fatal errors and warnings to an error_log file in the directory where the failing script runs. For a Zenphoto install in your document root, look for /home/USERNAME/public_html/error_log. In cPanel Jupiter, open Files > File Manager, navigate into public_html, enable Show Hidden Files (dotfiles) from the Settings button, and open error_log in the viewer. In DirectAdmin Evolution, use System Info & Files > File Manager and browse the same path. The newest lines are at the bottom, and they carry the exact file and line number, for example a message ending in zp-core/functions.php on line 214 or a database connection failure.

cPanel also exposes a filtered view under Metrics > Errors, which aggregates recent web server and PHP errors for your account. This is the fastest place to catch a 500 caused by .htaccess, because LiteSpeed logs the offending line there even when no PHP error_log is written.

If the log is empty or stale, force Zenphoto to reveal the error itself. Edit zp-data/zp-config.php in File Manager and set the debug constants near the top of the file:

$conf['debug'] = true;
$conf['DEBUG_LOG'] = true;
$conf['DEBUG_ERROR_LOG'] = true;
$conf['DEBUG_EXIF'] = false;

Older releases use define() statements instead; if you see lines like define('DEBUG_LOG', false);, flip those to true. With debug logging enabled, Zenphoto writes a detailed trace to zp-data/debug/debug.log. Open that file after reproducing the error and you will typically see the failing plugin, the SQL statement that failed, or the missing function. Turn these constants back off the moment you finish, because they can expose sensitive paths to visitors.

To see errors directly in the browser during a controlled test, add a temporary .user.ini file in public_html:

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

The .user.ini is honored by PHP running under LiteSpeed for your account only, and changes can take a couple of minutes to apply because of the PHP user config cache. Reload the failing Zenphoto page and read the message that now prints on screen. Remove display_errors = On once diagnosis is complete so real visitors never see raw errors.

Fixing PHP Version, Extension, and .htaccess Faults

Once the log names a cause, the fix is nearly always a UI toggle. If the message reads Parse error: syntax error, unexpected on modern syntax, or Call to undefined function for something Zenphoto expects, your gallery is running on the wrong PHP version. Open Software > Select PHP Version (MultiPHP / PHP Selector) in cPanel, or Account Manager > PHP Selector in DirectAdmin, and set the domain to a version Zenphoto supports for your release, typically PHP 8.1 or 8.2 for current builds. In the same screen, review the extension list.

Zenphoto's image engine breaks loudly without graphics support. A log line like Call to undefined function imagecreatefromjpeg() means the gd extension is disabled, and Class 'Imagick' not found means the Imagick module is off. Tick gd, exif, curl, mbstring, fileinfo, and zip in the PHP Selector extension panel and save. Zenphoto can use either GD or Imagick as its graphics library, so enabling GD is the safest baseline. After changing extensions, revisit Admin > Overview or Admin > Utilities > Setup inside Zenphoto; the setup page reports which libraries it detected and warns about anything still missing.

When the Errors view points at .htaccess with a message such as Invalid command or a 500 that appears only on gallery URLs, the rewrite rules are the problem. Rename the current file to .htaccess.bak in File Manager and reload the site. If the white screen or 500 clears, the file contained a directive LiteSpeed rejected, often a stray php_flag line or a duplicated rewrite block from a partial upgrade. Rebuild a minimal working ruleset:

RewriteEngine On
RewriteBase /
RewriteRule ^(.*)/?$ index.php?p=$1 [L,QSA]

Adjust RewriteBase to a subdirectory such as /gallery/ if Zenphoto lives below the document root. Zenphoto can also regenerate its rewrite rules from Admin > Options > General after you enable mod_rewrite URLs, so let the application write them rather than pasting rules by hand where possible.

Resolving Memory, Permission, and Database Errors

Large photo libraries strain PHP memory when Zenphoto generates thumbnails and sized derivatives on the fly. A log entry reading Allowed memory size of 134217728 bytes exhausted confirms the ceiling. Raise it through the .user.ini shown earlier with memory_limit = 256M, or through the PHP Selector's Options tab where the same value is adjustable within your plan's cap. Pair that with max_execution_time = 120 so derivative generation for big JPEGs is not killed mid-render. If you continue to hit the plan ceiling, pre-generate a cache from Admin > Utilities > Cache manager during quiet hours rather than letting every visitor trigger a heavy resize.

Permission faults show up as failed to open stream: Permission denied or Warning: is_writable() against zp-data or the cache folders. Zenphoto needs to write to zp-data/ and to the album cache/ directory. Using File Manager, set directories to 755 and PHP files to 644 via the Permissions dialog; never use 777, which CloudLinux and many security scanners reject and which is a genuine security risk. If a plugin created files owned by an unexpected process, delete the stale contents of cache/ and let Zenphoto rebuild them.

Database errors are the last common class. Messages like Error establishing a database connection or Access denied for user mean the credentials in zp-data/zp-config.php no longer match reality, usually after a migration or a password reset. Confirm the database name, user, host, and password by opening the database in phpMyAdmin from cPanel or DirectAdmin, then reconcile them with the $conf['mysql_...'] values in the config file. Keep the host as localhost on shared hosting unless your provider documents otherwise. If tables report as crashed in the phpMyAdmin operations view, select them and choose Repair table from the dropdown. With the message identified and the matching UI or config fix applied, disable every debug flag you turned on and confirm the gallery loads cleanly for an anonymous visitor.