An occasional problem with a Drupal-based website is when a developer runs into the dreaded white screen of death (WSOD). This can happen for a variety of reasons. Here I plan to chronicle the times I've encountered this problem and what my solutions have been.

PHP Memory Limit

There are times when the php memory limit that is set in your php.ini file is simply too low for whatever reason. Sometimes certain Drupal modules simply require more memory. Many times these modules will tell you in the README file that accompanies it. It's always a good idea to read this file, no matter what module you are installing; hence the name. If you do not have direct access to your php.ini file to change this setting, it can most likely be accomplished by adding a line in the .htaccess file in your web root directory. I recommend setting the memory limit to at least 128M, and the line to add in your .htacces file would look like this...

php_value memory_limit 128M

UTF-8 Byte Order Mark (BOM)

On occasion when using a shared hosting service (which many of the less expensive web hosting companies are), there is great sensitivity to the encoding of the files used on the site. There are occasions when this can cause problems depending on what text editor you or one of your developers is using or what their settings are on their text editors. On more than one occasion I've experienced a white screen because I had a custom file (for a custom module or theme, for example) that somewhere along its editing history became encoded as UTF-8 WITH Byte Order Mark. To fix this, all you need to do is open the file in a text editor that allows you to change a file's text encoding, and change the encoding to be UTF-8 WITHOUT Byte Order Mark. This is, in fact, such an issue that when you validate your site with the W3C, it will warn you if there is a file containing the byte order mark. Sometimes the presence of the BOM will cause Drupal to just output an error that begins, "headers cannot be modified".

My text editor of choice is BBEdit for the Mac, and it allows you to change the file's text encoding very easily. There are comparable editors out there that will meet your needs.

PHP Coding Issues

One of the most common code errors that cause a Drupal WSOD is white space at the end of a php file. Because of this, it is a Drupal coding standard to not include the closing ?> on a php file.

Also, some versions of PHP4 have problems with function declaration syntax. The simple solution to this is to make sure you are running PHP5 with your Drupal install. If not, contact your web hosting provider to see about upgrading.

Other Reasons?

If you've tried all of the above quick fixes and you are still pulling your hair out, try adding these lines of php code at the top of the index.php file in the web root directory. This code turns on all error reporting and tells php to display all errors and startup errors to the screen:

<?php
error_reporting(E_ALL);
ini_set('display_errors', TRUE);
ini_set('display_startup_errors', TRUE);
?>

All in all, the Drupal white screen of death is something that is not the end of the world, as much as it may probably feel to you the first time you experience it.