There are times when you run into an issue while maintaining your Drupal instance, when the problems are frustrating enough, yet the solution seemed to be extremely simple. Unfortunately, by the time you arrive at the solution, you’re already depressed by the amount of technical debt incurred in the process.

Therefore, I compiled a short list of common issues I run into whenever things take a turn for the worse. Although this might not cater to all problems, it should mitigate a good number of issues so you can focus on development and not disaster recovery!

None of my new code is executing on the site!

Difficulty Level: Easy / Intermediate

Problem: You just took your first step into module development, you enabled the module on your site (if not, this is one problem!), and none of the new hooks you’re trying out are registering on the site.

Diagnosis: Go into your database and execute the following query:

SELECT * FROM system WHERE name = <YOUR MODULE NAME>

Your module should show up whether the status is 0 or 1.  If it’s still 0, enable it.

Solution I: From the query, if you notice that the filename is showing a completely different path from where your actual code files are, you should adjust it so Drupal recognizes it.  It’s also a good sanity check to make sure disabling, uninstalling, and re-enabling the module will link the module correctly.  If you have drush installed, you can simply do all that by firing:

drush dis -y MODULE; drush pm-uninstall -y MODULE; drush en -y MODULE

Solution II: This is actually the first thing you should do every time you encounter any problem (it’s number 2 so the diagnosis and solution links nicely together in this article). Clear the cache and try again.  You can do this by navigating to the Performance section in site configurations (or fire this path /admin/content/clearcache). If you have drush, you can also clear cache by running drush cc all.

This is critical especially if you have certain hooks in your module (e.g. hook_theme, hook_menu), which rely on cached data for performance reasons.

My site is showing a blank / white screen!

Difficulty Level: Easy / ???

Problem: You might’ve installed a new module or made new changes to your code when suddenly, any or all pages you navigate to yields a blank, white screen. It’s frustrating because you don’t know what to do next. (For future reference, we’ll call this the white screen of death or WSOD).

Solution: This is mainly because there are fatal errors with your code. While there is no one solution to this problem, it will help if you enable error reporting on your environment so you can identify what the problems are exactly (before I continue, don’t do this on production for security reasons…and, well, it’s embarrassing! You don’t want the world to know why your site is broken!). Keep in mind that errors are usually suppressed

The easy way to do this is by putting the following in your settings.php file:

error_reporting(E_ALL);
ini_set('display_errors', TRUE);
ini_set('display_startup_errors', TRUE);

Otherwise, read your server software documentation on how to get this enabled (in the right staging /development environment, of course).

Pro-tip: Maintain separate settings.php files so that your development environment always has this enabled at all times.  It’ll save you a ton of time the more verbose your site is.

I got this “Allowed memory size of x bytes exhausted” error

Difficulty Level: Easy

Problem: Let’s say you enabled error reporting from the last section, and you get an error “Allowed memory size of x bytes exhausted.” The site churns slowly before it gives up and either gives you this error or shows you the WSOD.

Solution: This means that you need to increase your memory in your settings. This may be done in a few ways depending on what server software you’re using, but in most cases, you can simply add this line to your settings.php to avoid root changes to your configurations:

ini_set('memory_limit', '512M');

In most cases, you can go into your php.ini file and add this clause:

php_value memory_limit = "128M"

(Restart your server software if you go this route).

TAKE SPECIAL CARE WHEN SETTING THIS VALUE.  Finding a happy median will ensure your site will run at optimal speeds without sapping server resources. It may take some trial and error, but you’ll find the right value soon enough.  If this is not viable, contact your web host or administrator for other options or look into using less memory-hogging modules and/or algorithms.  Although it’s tempting to set a high value on your development environment, it’s always better to keep it as low as possible at all times so you don’t balloon an issue to something even worse.

Reference: https://drupal.org/node/76156

All pages on my site link to the front page only!

Difficulty Level: Moderate

Problem: Ever encountered a scenario where no matter what pages you navigate to, it always leads to the homepage?  Even typing in direct URLs (e.g. www.example.com/about) still yields the same behaviors?

Diagnosis: Try typing in paths you know except with a q= at the end. For example, try www.example.com/q=about/my/company

Solution I: If your pages do start showing up, navigate to /admin/settings/clean-urls or /admin/config/search/clean-urls (or, in this case, try www.example.com/q=admin/settings/clean-urls or www.example.com/q=/admin/config/search/clean-urls) depending on whether you’re using Drupal 6 or 7 and enable clean URLs. You might have to log in using www.example.com/q=user.

Solution II: But what if clean URLs are already enabled? You might also need to check your server configurations to see if the extension to handle path aliasing is enabled. You might have to log in as root to make sure this is the case.

Check the following (note: the following is for apache servers only):

1. Check that your vhost for your site has the AllowOverride All in the settings like this:
   <Directory /path/to/site/>
      Options Indexes FollowSymLinks MultiViews
      AllowOverride None
      Order allow,deny
      allow from all
   </Directory>

2. Just in case, make sure you have the following line in your htaccess file
   RewriteEngine On

3. Worse comes to worse, log in as root (or an admin account), and enable the extension in your server software.  In most cases, if you’re using apache, you can simply achieve this by executing this one liner in the terminal:
   a2enmod rewrite
   Restart apache afterwards (service apache restart or service httpd restart depending on what OS you’re using.  The examples are for Ubuntu and CentOS respectively)

It works fine on my end, but everyone else is seeing something different

Difficulty Level: Moderate to Difficult

Problem: You may have a feature that seems to work fine on your end, but other people are reporting that they are finding odd behaviors like the page or feature doesn’t exist or they are showing old renditions…

Ideas: There is no silver bullet to this problem, but it may help to ask a few questions (for the purpose of this section, I also included some example scenarios, as well!)

• Is the feature designed in javascript and executed on the client-side? (In most cases, old code might be cached on the browser.  Clear the browser cache locally)
• Are there caching modules enabled on the site (e.g. memcache, varnish)? (You might need to make sure they’re cleared properly or set the TTL to a lower value.)
• Is it working for you as admin or another role? Is the feature highly permissions-reliant? (Stepping through the problem will help big time, but the devel module might be key here if traditional methods are too cumbersome).
• Does the end user have a certain browser plug-in that’s preventing them from accessing certain content? (For example, if you’re testing the site, and wondering why certain images or ads may not work, browser plugins like ad block may be the culprit).

I have some features in my hook_block definition that appear then disappear inconsistently, and I don’t know why!

Difficulty Level: Difficult to comprehend at first

Problem: You like being neat, and your site has a ton of blocks that are placed via panels or contexts, and you only want to load all the assets relevant to the block within hook_block like so:

function my_module_block_view($delta = '') {
 switch ($delta) {
   case ‘block1:
     drupal_add_js('js/script.js');
     $block['subject'] = t(‘My block’);
     $block[‘content’] = block1_content();
     break;
   case ‘block2’:
     drupal_add_css(drupal_get_path('module', my_module) . '/css/style.css');
     $block['subject'] = t(‘My other block’);
     $block[‘content’] = block2_content();
     break;
 }
 return $block;
}

However, it sometimes works and sometimes it breaks your block features and layout on production, no matter what kind of caching configurations you have.

Solution: Only leave static HTML content that you would like to cache within the block content. Try to add elements that fail to get loaded into cache outside the block in another layer such as hook_init() or the [‘#attached’] value in the render array (I mention both approaches depending on what version of drupal you use).

Functions like drupal_add_js() and drupal_add_css() fail to work within these cached entities because the functions intertwine with other static components of the site (there is one rendition of compressed javascript and css), and for them to only be included sometimes will lead to consistency issues down the road when cron clears cache (at that point, you’re gambling on whether the function calls will get included or not.

Conclusion

Reading this article will not solve all your problems. However, fixing these issues will not only enhance your knowledge of Drupal but also improve your debugging skills in general. It is also extremely helpful to make use of Drupal.org and other collaborative forums such as Stack Overflow to get other’s experiences on the problem and also make the documentation on these issues more prevalent.