Why Piwigo Fails Silently

Piwigo is a PHP application that leans heavily on the GD or ImageMagick extensions for thumbnail generation, writes session data and cache files to local directories, and stores every album, image reference, and configuration flag in MySQL. When any one of those dependencies shifts underneath it, the gallery can stop rendering entirely. On a shared LiteSpeed stack running CloudLinux, the most common trigger is a PHP version change: a MultiPHP update to PHP 8.2 or 8.3 can break an older Piwigo release or a third-party plugin that still calls deprecated functions, and the result is a blank white page rather than a readable error.

The reason you often see nothing at all is that production PHP configurations disable display_errors by default, which is correct for security but unhelpful during diagnosis. When a fatal error occurs, PHP halts execution and sends either an empty response (the white screen of death) or a generic HTTP 500 that the browser renders as a server error page. The actual message — the file, line number, and the class or function that failed — is written to a log file, not to the screen. Your first job is always to locate that message, because fixing Piwigo blind leads to guesswork and wasted effort.

There are a handful of recurring root causes worth keeping in mind as you work: a PHP extension that Piwigo requires (GD, mysqli, exif, or mbstring) is not enabled in PHP Selector; the memory limit or max execution time is too low for batch thumbnail regeneration; file and directory permissions were reset during a migration or restore; a plugin or theme was updated to a version incompatible with the current core; or the _data cache directory contains stale compiled templates. Each of these produces a different fingerprint in the logs, which is why reading them first saves hours.

Finding the Real Error in Logs and Debug Mode

Start with the per-site error log, which LiteSpeed and the CloudLinux PHP handler write into the directory where the fault occurred. In cPanel Jupiter, open File Manager, navigate to your Piwigo root (commonly /home/USER/public_html or a subfolder like /public_html/gallery), and look for a file named error_log. Enable Show Hidden Files from the File Manager settings so dotfiles are visible. In DirectAdmin Evolution the same file appears through File Manager in the domain's document root. Open it, scroll to the bottom, and read the most recent timestamped entry. A typical fatal line looks like this:

[04-Nov-2026 09:12:44 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function imagecreatetruecolor() in /home/user/public_html/include/functions_picture.inc.php:218

That single line tells you the GD extension is missing. A different entry pointing at Allowed memory size of 134217728 bytes exhausted tells you the memory limit is the bottleneck. If the error_log file does not exist or is empty, force PHP to populate it by creating a .user.ini file in the Piwigo root with logging turned on:

; .user.ini in Piwigo document root
display_errors = Off
log_errors = On
error_reporting = E_ALL
error_log = /home/USER/public_html/piwigo_error.log

Replace USER with your account name and reload the page that throws the 500. The .user.ini file is honored by the CloudLinux PHP handler, but changes can take up to five minutes to apply because of the ini cache TTL; if you need it immediately, touch the file again or wait out the interval. Keep display_errors off on a live gallery so you never leak paths to visitors.

Piwigo also ships its own debug facility. Append ?debug=1 is not supported universally, so instead edit local/config/config.inc.php through File Manager and add $conf['show_php_errors_on_frontend'] = true; on a line before the closing PHP tag, or set the database-driven debug flag. For deeper tracing, Piwigo writes SQL and timing data when you define define('IN_ADMIN', true); contexts, but for most 500s the combination of the hosting error_log and the .user.ini capture is enough to name the failing function or query. Always note the exact file path in the trace — it distinguishes a core fault from a plugin in /plugins/ or a theme in /themes/.

Fixing PHP Version, Extensions, and Resource Limits

Once the log names the cause, most fixes live in the control panel rather than the filesystem. If the trace shows an undefined image function, open Select PHP Version (cPanel) or PHP Selector under the CloudLinux section (DirectAdmin). Confirm the active version matches what your Piwigo release supports — current Piwigo runs cleanly on PHP 8.1 and 8.2, while very old installs may still expect 7.4. Then open the Extensions tab and tick gd, mysqli, exif, mbstring, json, and zip. These are the modules Piwigo and its common plugins call. Save, then reload the gallery; the undefined-function fatal should disappear.

For memory-exhaustion and timeout errors during bulk uploads or thumbnail regeneration, use the Options tab of the same PHP Selector screen to raise memory_limit to 256M, max_execution_time to 120, post_max_size to 128M, and upload_max_filesize to 64M. If your panel caps those values, set the same directives in .user.ini:

memory_limit = 256M
max_execution_time = 120
upload_max_filesize = 64M
post_max_size = 128M
max_input_vars = 3000

If the white screen only appears after enabling a specific plugin, the log will point into that plugin's directory. Disable it without touching the UI by renaming its folder in File Manager — change /plugins/BrokenPlugin to /plugins/BrokenPlugin.off. Piwigo will no longer load it and the admin dashboard becomes reachable again, where you can uninstall it properly. The same renaming trick works for a theme under /themes/; once the gallery loads, switch to the default elegant theme from Administration > Configuration > Themes. Clear the compiled template cache by deleting the contents of /_data/templates_c/ and /_data/combined/ after any version or theme change, since stale Smarty templates frequently cause fatals that survive the real fix.

Permissions, Database Connections, and .htaccess Conflicts

A large share of 500 errors after a restore or migration come from permissions. Piwigo must write to /_data/, /upload/, and /local/. In File Manager, set directories to 755 and files to 644; never use 777, which the LiteSpeed suEXEC model treats as unsafe and may refuse to execute. Right-click each writable folder, choose Change Permissions, and apply recursively. If the log shows a session write failure, confirm the session.save_path is writable or point it at a folder you own via .user.ini.

When the error reads Connection to server failed or Access denied for user, the problem is database credentials in local/config/database.inc.php. Open it in File Manager and verify $conf['db_host'] is localhost, and that the username, password, and database name match what you see in cPanel MySQL Databases or DirectAdmin's database manager. On shared hosting the user and database are prefixed with your account name, so a dropped prefix after migration is a frequent culprit. Use phpMyAdmin to confirm the piwigo_config and piwigo_images tables exist and are not marked as crashed; if a table reports a problem, run Repair table from the phpMyAdmin operations menu.

Finally, inspect the .htaccess file in the Piwigo root. A directive copied from another server — a php_value line, a php_flag, or a handler definition — can trigger an immediate 500 under LiteSpeed because those directives belong in .user.ini instead. Remove any php_value/php_flag lines and keep only the standard rewrite block:

# Piwigo .htaccess
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
</IfModule>

Reload after each change and re-read the log; a clean log with a rendering gallery confirms the fix. Work one variable at a time — version, then extensions, then limits, then permissions — so you always know which change resolved the fault and can revert cleanly if a symptom returns.