Drupal 7 troubleshooting checklist

By April 5, 2015 Drupal No Comments

New to Drupal or a little rusty? This checklist is to help speed up your troubleshooting process. The list is currently at version 0 and I hope to improve it by giving more structure along with associating/clustering each item with symptoms. Let me know if you want to help!

How to use: Check through this list from top to bottom when something’s not working like it’s expected to. Items near the top are what I find most commonly occur and those below less so.

Theme functions or hooks not working
Template files not working.
White page of death (WSOD)
Contributed module not working
Not getting a call from external API/services
Entity metadata wrapper cheat sheet

Theme functions or hooks not working

  1. Have you checked recent logs?
  2. Is the extension correct?
  3. Is there a missing .tpl in the file name?
  4. Is the naming of the function (prefix of module name) correct?
  5. Have you double checked the spelling letter by letter? Look out for ‘_’ v.s. ‘-’, ‘__’ v.s. ‘_’.
  6. Did you flush Drupal’s cache?
  7. Did you make sure the flushing actually happened?
  8. Did you flush the correct cache (class / css/ page and else, etc.)?
  9. Is the file on the server? Did you git pull on server?
  10. Was the git pull successful?
  11. Are there committed changed on the server not pushed to remote repo that is overwriting your changes?
  12. Did you clear your browser cache?
  13. Have you tried opening the page in an incognito window?
  14. Is the module enabled?
  15. Are the paths correct?
  16. Have you double checked the path letter by letter?
  17. Is the file you are editing loaded by Drupal? Is it module_load_include’d somewhere or defined in the module’s .info file?
  18. Is the module weight affecting the processing order? Have you tried changing the module weight and clearing all cache?
  19. Have you turned off block or page level caching?
  20. Are you using the correct DB?
  21. Is the module in the right folder?
  22. Does the folder have the right permission for the web server user?
  23. Is the template (.tpl.php) file being overridden downstream? For example if you are editing the template file within a module, a template file with the same file name in the theme would override it.
  24. Is the block in the right region?
  25. Are the targeting css classes, ids, element types, correct?
  26. Is there an extra hide($content[‘xxx’]); that is hiding your content?
  27. Is the hook function supposed to return something? Check the docs. Some hook implementations alter the variables passed in by reference, some are expected to return something.
  28. Is the hook implementation’s parameters correct? Should anything be passed in as reference but not so?
  29. If it is an alter, remember the function name pattern is [module name]_[hook_name]_alter.
  30. If it is an alter, is some other module overriding your changes?

Template files not working.

  1. If you are implementing a template with a base template? For example, node–article.tpl.php requires the base node.tpl.php to be present in the same theme.
  2. Are the right theme_hook_suggestions present? Try dpm() $variables[‘theme_hook_suggestions’] in your hook_preprocess_node(&$variables).
  3. Is the template file named correctly? The ‘_’ in theme_hook_suggestions or hook_theme()s are replaced by ‘-’ by default unless specified otherwise in hook_theme()s.
  4. Are you using the right theme? Has the theme been enabled?
  5. Have you flushed your theme registry? drush cc theme-registry.
  6. Are you using the right view mode?

White page of death (WSOD)

  1. Have you checked the web server error logs?
  2. If a new function was added recently, have you checked for a function naming conflict? It may not be your problem – some other module may have wrongly named the function. Check the include files on top of the .module files of the current module too.
  3. Does the folders and files have the right permission for the web server user?
  4. Did you upload that file / deployed that repo in the right place?
  5. Was a file not included in the repo? Some files can be excluded by .gitignore and not show up in git status.
  6. Are you accessing the correct address? Are you accessing the correct instance? Only applicable in a multi-instance environment.

Contributed module not working

  1. Is the module really enabled?
  2. Have you checked the installation steps outlined in the module’s project page on drupal.org?
  3. Is there any required library missing?
  4. Have you checked the status report for any other requirements?
  5. Have you flushed cache?
  6. Have you set up new permissions this module may have defined?
  7. Have you checked version compatibility with other contributed modules?
  8. Did you download the right version of the module?
  9. Did you download the right module?
  10. Have you re-read through the details on the module’s project page on drupal.org?
  11. Have you searched through the issue queue for the module?
  12. Have you ran update.php?
  13. Does the folder have the right permission for the web server user?

Not getting a call from external API/services

  1. Is your web server password protected?
  2. Is your web server accessible?
  3. Are you checking the correct instance?

Entity metadata wrapper cheat sheet

// Source: http://drupal.stackexchange.com/a/98514
$wrapper->author = 0;
$wrapper->url = 'dummy';
$wrapper->author->mail = 'foo';
$wrapper->author = NULL;
$wrapper->body->set(array('value' => "<b>The second body.</b>"));
$wrapper->body->set(array('value' => "<b>Der zweite Text.</b>"));
$wrapper->author = $user->uid;
$wrapper->{$property}[0] = '2009-10-05';
$wrapper->field_image = array('fid' => $file->fid);
$wrapper->parent[] = $term_parent2;
$wrapper->field_tags[1] = $term_parent;
$wrapper->field_tags = NULL;
$wrapper->field_text[0] = 'the text';
$wrapper->field_text[0]->set(array('value' => "<b>The second body.</b>"));
$wrapper->field_text2->summary = 'the summary';
$wrapper->field_text2->value = 'the text';
$wrapper->field_file[0] = array('fid' => $file->fid, 'display' => FALSE);
$wrapper->field_file[0]->description = 'foo';
$wrapper->field_file[0]->display = TRUE;
$wrapper->field_file[1]->file = $file;
$wrapper->field_file[] = array('description' => 'test');
$wrapper->field_file = NULL;
$wrapper->field_image = array('fid' => $file->fid);
$wrapper->field_image->alt = 'foo';
$wrapper->field_image->file = $file;
$wrapper->field_image = array();
Generated from entity.test via:
# grep "^\W*\$wrapper->" entity/entity.test | tr -s " "