At some point or another, everybody who has worked with Drupal has encountered a bug or piece of functionality that didn’t work as expected. This isn’t an indictment of Drupal itself, but rather a reality of software in general. No matter how well-engineered the code, sometimes things break or run into unforeseen conditions.

One of the great things about Drupal being open-source is that you as the user have an opportunity to dive into the code and configuration of the module that is giving you trouble, and potentially solve and contribute the solution for the rest of the community. But to get to that level of contribution or even just custom development in Drupal, one needs to develop a strong understanding of how to approach “debugging”.

Find a Bug, Fix and It

In its most simplest description, debugging is basically just the process of finding a bug and fixing. Of course, the practice of fixing those bugs isn’t necessarily so simple, but looking at the process in that kind of mental framework can help reduce apprehension about diving into this kind of work.

No Wrong Way to Debug

While different people might have preferences as to how they approach debugging, if you are finding bugs and fixing things, you are doing OK. You certainly want to take care to not make problems worse, possibly by creating new bugs unintentionally, but that is really a measure of experience. Ultimately, if you create new bugs, you will find and debug them as well.

Preventative Care

It is advantageous to prevent bugs from being saved into your codebase in the first place, so making use of tools that facilitate that is encouraged. Various IDE’s (Integrated Development Environments) such as PHPStorm, have features such as spell checking, syntax and function analysis, in order to evaluate your code for potential mistakes. Many bugs are caused by such mundane mistakes like typos, so these tools can be quite helpful.

Other tools like the Drupal Coder module, which you install in your Drupal website project, can help evaluate your code at a Drupal-specific level, to ensure you follow Drupal programming guidelines and avoid using deprecated functions and features.

Tools of the Trade - Print Debugging

Print debugging is a method where you tell your program to output information, such as variables or function returns, so you can inspect what is happening with your code. This will involve using PHP functions like var_dump(), and debug_backtrace(), as well as Drupal specific functionals provided through the Devel module such as dpm(), ksm(), kpr() etc

Since this approach doesn’t require an IDE, it can be fairly simple to understand and to get started with. However there is no-step through process, limiting the context of the output you can review. You most likely won’t be able to access private or protected variables, and it can be easy to forget to remove debug code. Despite those drawbacks, this kind of methodology is a great way to get started with debugging.

Tools of the Trade - Live Debugging

Live debugging is about using specialized software tools like Xdebug or Zend debugger to actively watch what is happening with the output from your program. This method is great because you can pause program execution at assigned breakpoints, and “step forward” and “backward” through code. This provides a great deal of context as to what’s happening and tells you much more than just outputting the results. Additionally, you likely have access to all in-scope objects and variables. This helpful functionality can be difficult to get setup though, as it requires some specialized configuration with an IDE.

Important Rule to Follow

Don't Hack Core or Contrib

It might seem tempting to change even a small amount of code in a core file or contributed module in order to fix what is going wrong, but trust me, it isn’t worth it. More often than not, these small “fixes” will turn into larger problems down the road. If you are working with a team, this is guaranteed. Look for issues in the issue queue that may have patches for what  you identified, or better yet, submit the patch yourself.


Skim, Hack, Pray

Put simply, this approach has you skim through the code, find and change something, and then pray that the error goes away. As funny as this sounds, it can be quite successful even if maybe relying on a bit of luck. It can work well enough for syntax issues and semantic errors, but unfortunately it can become an inefficient approach very quickly.


Backtracing is a process that relies on using PHP functions like debug_backtrace() to review the sequence of events or function calls that brought your misbehaving program to the place where it presents errors. You can pick a spot, set a breakpoint, and then work backwards through the stack trace to see how you go to where you are.

Step Forward

Stepping forward is sort of the opposite of the backtrace, where we try to focus on what comes next in the program’s sequence. Much like backtracing, you’ll pick a spot and set a breakpoint in the code, and then step forward through the program a bit at a time until things start braking.

Initial First Steps

Turn on Logging

The more information you have about what your Drupal website is doing or trying to do, the easier it will be to figure out how it has gone wrong. So, first of all turn on logging, so that you can get as much information as possible. You’ll find options for error display and logging in the Development menu section of your Drupal website navigation.

Disable Caching

The caching of page renders can sometimes mask problems, or in fact cause issues as well. To make sure you are seeing a fresh version of what Drupal is trying to build with your code, be sure to have all caching disabled. You’ll also find these settings in the Development and Performance pages of your Drupal website.

Display all Errors

By default Drupal and PHP may not show all types of errors when something goes wrong. There are obviously different types, but also degrees of severity. Read this handy guide on settings configuration for your Drupal website to have more granular control of this error output.

Common Types of Drupal Bugs

To help you get started in your debug adventure, we’ve outlined some of the more common types of bugs you might encounter. Keep in mind this isn’t an exhaustive list, you will always find something new and baffling the longer you stay a developer, but this list should hopefully help you identify some common issues.

Syntax Errors

  • Missing semicolon: PHP statements need to be terminated properly, easy to miss.
  • Unexpected EOF: Unexpected end of file, sometimes caused by not closing our your PHP tags.

Semantic Errors

  • Access violations (undefined index): Referencing variables or keys that don’t exist or don’t allow you access can cause problems.
  • Incorrect API usage (db_query() instead of node_load()): Different versions of Drupal also might use or have available different versions of API functions.

Logic Bugs

  • Infinite loops: It would be nice if your code could run forever, but it isn’t advised.
  • Division by 0: Much of programming is math, and this one is pretty firmly denied.

Security Bugs

  • Missing check_plain(): Drupal has various formatting functions to provide extra security against malicious code and behavior. Please use them.
  • PHP input filter (gone in D8!): The PHP filter provided a gaping hole in Drupal security, thank goodness it is on the way out. Make sure your code and modules recognize this

* * *

Good luck debugging! If you find yourself needing more advanced help, don't hesitate to reach out to us. We love solving problems!