Drupal White Screen of Death Solutions
Have you ever seen an error on your Drupal site that says:
“The website encountered an unexpected error. Please try again later.”
There are over 700 people who have reported the same problem on the Drupal.org forums.
If you have this error or similar errors and are thinking, “OMG! Now what?”, then hang tight.
We’re here to help with this tutorial. We’ll show you how to diagnose and solve errors that appear on your Drupal site.
Print Errors to the Screen
If you see an error with no information or you see the White Screen of Death (WSOD), one of things you should do is start looking for errors.
To make errors visible on your Drupal website, find the index.php file in the main directory of your site. Open index.php and add this code directly before the very first line of the file:
error_reporting(E_ALL); ini_set('display_errors', TRUE); ini_set('display_startup_errors', TRUE);
In the example below, I have an error with the Weather module. I have deliberately loaded the Weather module to one of my test sites in an unconventional way and broken the code in an effort to trigger an error:
This error tells me that something is wrong on line 629 of weather.module. Of course, if this was a production site and errors were not enabled to print to screen, a WSOD would send me running to my error logs to see the same message.
(As a side note, it is not common practice to upload the weather-7.x-1.5 directory and it had nothing to do with triggering an issue.)
Find Your Error Logs
Let’s assume you got a WSOD and need to look at your error logs. I am not a server expert but I can tell you where my error logs are located. As you can see from the screenshot above, my error logs are at the same level as my html directory. The html directory is where your Drupal files and directories are stored.
View the Errors
The control panel I have on my server allows me to check a box and click edit, as shown in the screenshot above. If your server doesn’t have this feature, download the error log file and view it locally.
As you can see, it’s telling me the line 629 in weather.module has an issue. It also says it can’t find a favicon.ico file. Hmmm. I’ll have to fix that. Anyway, now that I know where to look for the problem, I can open weather.module and see what might be wrong.
Restoring Your Site
Some issues are triggered when a user lands on a specific page while others seem to affect all your pages. If for some reason, you can’t reach /#overlay=admin/modules or /admin/modules and disable the problem module, try the following.
- Launch PHPMyAdmin. I can access it by going to my domain.com/myadmin. If that doesn’t work, ask your service provider for help.
- Select the database .
- Click on the browse icon for the System table.
- Locate the record with a path to your module. In this example, the path is sites/all/modules/weather-7.x-1.5/weather/weather.module.
- Click the little pencil icon to edit the record.
- Locate the status and observe the value is 1.
- Change the status value to 0.
- Click Go.
- Return to your site and refresh.
You should be able to access your site again. If you go to the modules admin page, you will see the module is disabled. If you go to the Uninstall tab, you will see that it is waiting to be uninstalled. If you uninstall the module via the Drupal admin interface, the module directory is still on your server and still available to enable again.
Now that you have your site back, your next step is to resolve the problem so that you can use the module.
Opening a Module File
Because the line number is a clue to where I will find the problem, I have down loaded the weather.module and opened it in Notepad++. You could use any code friendly application that shows line numbers. I scrolled down and found line 629. As you can see from the screenshot, there is a rogue <?php tag. Of course, I put it there to break the module so I could do this demo.
Finding or Reporting the Issue
If this had been a real issue, after I restored my site and investigated line 629, I would have returned to the project page on Drupal.org and searched the issue queue. The probability that someone else has posted the issue and possibly a fix is high. There could be a patch waiting for me. If you need help applying a patch, check out http://www.ostraining.com/blog/drupal/patches/.
If there isn’t a post in the queue yet, create one. Be sure to include the error message.
Summary
In this blog, we went from a vague error message to a solution. The trick to surviving the world of content management systems and error messages is to know where your error logs are located and look at them. I can’t tell you how many times I have come across an issue, looked at the log, and scratched my head. Not all errors are easy to interpret. That’s where a great hosting service is your friend. I create a ticket and ask, “Can you help me understand what’s wrong and how to fix it?” If the error has something to do with a setting on the server, the server guys will be able to help. In our example, my server guy would have told me to seek out the coder of the module.
Happy debugging!
Sorry guys. Human error late on July 3rd.
I’ve added an explanation to the blog.