Common Drupal Problems - Solutions Included

Whether you are a Drupal newcomer or a seasoned Drupal developer, you're bound to run into one, some, or all of the issues outlined below. Some are obvious, some not so obvious, but we'll show you how to troubleshoot them all regardless.

Some of these issues took a while to troubleshoot, so if you use Drupal as much as we do, make sure you bookmark this page for easy reference in the future. There is nothing worse than spending hours on a problem that can be solved within minutes with the right information (we've all been there).

1. If you’re working on a Drupal 8 site and you get the message "The provided host name is not valid for this server," you’re not alone. This is a result of a feature added to Drupal 8 to protect against HTTP Host Header attacks.

   1. To fix, set the $settings['trusted_host_patterns'] variable in your settings file.

   2. If you are running from one hostname, like www.mysite.com, you’d set it like so:

      $settings['trusted_host_patterns'] = array(
        '^www\.mysite\.com$',
      );

   3. For more information, check out this StackExchange post.

2. Configuration management in Drupal 8 is great! But you might run into one thing thing that bugs you - for example, if you override a configuration value within settings.php there is no indication in the UI that the values were actually overridden. This is a complete 180 from Drupal 7, which displayed overridden values within the UI. Right now, there is no official solution to this problem, unfortunately, but here are two things you can do:

   1. This issue on drupal.org has an actively worked on patch that you can use: https://www.drupal.org/node/2408549
   2. The Configuration Update Manager contrib module can give you this info.

3. Kint is a great and detailed new debugging tool in Drupal 8, but it very often runs out of memory when you’re debugging within a Twig template, which defeats the purpose of using it.

   1. The first option is to just output one variable if that’s all you need to see, like so - but be aware that even just one variable can be a giant object, so try to be as direct as possible:

      {{ kint(content.field_name['#items'].getValue()) }}

   2. The next option is to limit the number of output levels. You can do so in a number of ways:

      1. In settings.php:

         require_once DRUPAL_ROOT . '/modules/contrib/devel/kint/kint/Kint.class.php';
         Kint::$maxLevels = 3;

      2. Create a /modules/contrib/devel/kint/kint/config.php file and add / modify the line:

         $_kintSettings['maxLevels'] = 3;

      3. In a preprocess function, add the following:

         kint_require();
         Kint::$maxLevels = 3;

   3. When Kint loads the object you’re debugging onto the page, don’t click the plus sign! That expands the whole tree. Click the block instead, and click what you need from there.

   H/T Stackexchange

4. Many developers rely on Drush to do a variety of tasks, such as drush uli to log in to sites. If the site uri isn’t specified correctly, you’ll get a url of http://default instead of the correct url. Setting the $base_url of the site in settings.php doesn’t affect Drush. There are two options.

   1. When you run a Drush command that requires the uri, such as drush uli, specify the uri, like so: drush uli --uri=example.com.

   2. Set the uri in drushrc.php. If you don’t have this file already, you can simply create it in sites/default and put the following:

      /**
      * @file
      * Provides drush configuration to example.com.
      */
      
      $options['uri'] = 'http://example.com';

5. Generally, when you’re developing, you don’t want your CSS and JS cached, so that you can debug it. An easy way to make sure caching is turned off is to put these lines in your settings file:

   /**
    * Disable CSS and JS aggregation.
    */
   $config['system.performance']['css']['preprocess'] = FALSE;
   $config['system.performance']['js']['preprocess'] = FALSE;

6. MAMP is a fantastic local development tool, but it can sometimes be tricky to set up with Drupal and Drush. Are you getting an error similar to this when using Drush, but the site works fine?

   exception 'PDOException' with message 'SQLSTATE[HY000] [2002] No such file or directory' in core/lib/Drupal/Core/Database/Driver/mysql/Connection.php:146

   There’s an easy fix. Add the following to your database credentials within your settings.*.php file:

   'host' => '127.0.0.1',
   'unix_socket' => '/Applications/MAMP/tmp/mysql/mysql.sock',

   H/T to Modules Unravelled for this fix!

7. A lot can go wrong if your files and directories are not properly secured. The extended documentation can be found here.

   1. sites/default/files: This directory should have the permissions rwxrwx--- or 770
   2. You can use the File Permissions module to correctly set up your file permissions, especially if you are seeing errors about your sites/default/files and sites/default/private directories being incorrectly set up.

8. You’re setting up a new Drupal installation, or doing something new in an existing one, and boom, a white screen. What do you do? There are a handful of options for debugging. Here are a few to get you started:

   1. Check your error logs! Look at your Drupal, PHP, and Apache logs.
   2. Make sure you have error reporting on. Follow these directions to turn it on and in many cases, get the errors printed on the WSOD: https://drupal.stackexchange.com/a/54241
   3. Here’s a debugging tactic to tell you which module may be hanging up your site and causing the issue: https://drupal.stackexchange.com/a/105194
   4. Increase your PHP memory limit!

Did we miss anything?

Have a troublesome common bug? Reach out to us on twitter @ChromaticHQ!

Here are the first 15 Drupal problems we published in 2013 - you may still find some of these useful, though some may be out of date.

1. Users with 'edit page content' access cannot edit simple pages. Chances are the nodes that the users are trying to edit have an input format that they're not permitted to use. Try this:
   1. Check the input format for the body field. If its "Full HTML" or "PHP Code" for example, and that user role cannot create content of that input type, they won't even see an edit tab for that node. Either change the input format to one they can access, or grant access to that input format at: admin/settings/filters
   2. Double check that their role has permission to edit that particular node type at admin/user/permissions
   3. [Editor's Note 2017: These input formats may be insecure, so if you are running into this issue, reconsider using them, and use Filtered HTML instead!]
2. My client cannot see content he/she has created after logging out. This is likely a caching issue. They can see the content when they are logged in because some caching instances are based on user roles. Check the following:
   1. Clear cached data at admin/settings/performance.
   2. Clear your browser's cache.
   3. Adjust the "Minimum Cache lifetime" setting also under admin/settings/performance.
3. Images within posts are disappearing after publishing the node. This is likely related to the "Input Format" (again). If the node is using the default settings, "Filtered HTML," input format tags such as img, object, script, etc. will be stripped out. Try the following:
   1. Grant the role in question access to the "Full HTML" input format.
   2. Create a custom Input Format that includes the tags you want.
   3. [Editor's Note 2017: These input formats may be insecure, so if you are running into this issue, reconsider using them, and use Filtered HTML instead!]
4. My theme (CSS/template) changes aren’t showing up.
   1. Is CSS caching turned on? If so, turn it off while your theme is still under development. You can do so at admin/settings/performance.
   2. If that still doesn't work, try clearing your browser's cache
   3. If you're using Drupal 6, you may also need to clear out the theme registry if you have added new theme functions or new templates. While you're at admin/settings/performance, you can hit the "Clear cached data" button. Check out a full write-up about the new theme registry.
5. I’ve lost all my anonymous user content! (comments).
   1. When was the last time you imported/exported your database? This issue seems to happen when MySQL creates the user's table from a batch file (or database transfer via Navicat) – the user id from the table is auto-incremented and the required ‘0’ value is replaced. Try the following:
   2. Manually reset the uid value for the anonymous visitors in the users table. More info found at drupal.org.
6. I'm getting the dreaded white screen of death! There are many possible causes for this: PHP error reporting settings, memory exhaustion, etc. Try the following:
   1. Read this article on Drupal.org.
7. My web pages take forever to load. What’s the deal? Obviously, there could be many factors at play with this one. Try using the caching capabilities of Drupal. Caching can drastically improve the load times. Especially compressing CSS and JavaScript files - this will help reduce the number of header requests.
8. It’s a pain to try and develop a theme starting with Garland. Isn’t there a better way to theme from scratch? Yes, there is. Install the Zen theme starter kit. Zen makes it easy to theme from scratch, and best of all, Zen is a standards-compliant theme.
9. My blog gets hit with a ton of spam, what can I do? 1 word: Mollom; install the Mollom spam module, configure it, and you’ll forget that spam ever existed. Mollom has a free and a paid version - the free will be sufficient for most sites and it even includes some impressive statistics reporting.
   • [Editor's Note 2017: Mollom will no longer be supported as of 2 April 2018]
10. How can I figure out which theme function (or template file) I need to override in different places? Install the Devel module. The Devel module was created specifically for Drupal developers. It will streamline your Drupal development process by showing you which functions/templates were used to render parts of the page.
11. My layout looks “broken” all of a sudden, what happened? This may be a CSS issue, it may be a caching issue, or it may be something else. Try emptying the cache (admin/settings/performance) or try rebuilding the theme registry. Side note: you can easily empty Drupal's cache and rebuild the theme registry using the menu provided by the Devel module mentioned above.
12. CSS images disappear when caching CSS caching is turned on. There are a number of potential causes for this:
    1. Check the permissions to the files and CSS folders at (sites/default and sites/default/files/css respectively) - the server needs read and write access.
    2. Is your CSS file importing another with @import? This could be breaking things. Try embedding the imported CSS directly.
    3. Are you using relative or absolute paths? There seems to be an issue with this as well.
    4. Do you have any funny characters in your URL? While working on a local version of one our sites, we had parenthesis in a directory name; this was breaking the link.
13. My custom URL alias keeps being overridden! If you have the Pathauto module installed, it might be overriding your custom URL. To fix this, uncheck “Automatic URL Alias” under the URL alias fieldset – this will allow you to use your custom URL in conjunction with the Pathauto module. Also, there is a patch that apparently fixes this issue - though we have yet to test this.
14. Users cannot view/edit custom CCK field(s). Do you have the “Content Permissions” helper module enabled that comes packaged with CCK? If so, check the field permissions for that user role. By default, only users with administer CCK privileges can edit/view each field.
15. A specific Drupal user isn’t able to perform a necessary task (such as editing a specific content type). Double check the permissions for the user’s Role(s); they probably don’t have sufficient privileges to carry out the task.