Debug Drupal Code for Drupal 7, 8, 9, and 10

Debugging is one part tools, and one part process.

Debugging tools can help you gather additional information about the state and context of your application when performing different tasks. There are generally two reasons that you’re interested in tools for debugging Drupal: either your site or some specific feature isn’t working, or you’re ready to take a peek behind the curtain and learn more about how a specific feature works.

Knowing what to look for, and where to start looking, requires practice and a methodical approach. As you become more familiar with Drupal, debugging will become faster and easier as you’ll recognize common symptoms and know how to treat them.

Additionally, we firmly believe that stepping through the code using tools like a debugger or analyzing what your code is doing with a profiler is one of the best ways to truly understand Drupal’s APIs.

Example tasks

  • Figure out why your Drupal site is displaying a white screen of death
  • Locate problems in code so that you can fix them
  • Learn how a feature or API in Drupal works by stepping through the code as it executes


New tools to assist with debugging will continue to be developed. At the same time, existing tools are unlikely to become irrelevant anytime soon—especially those that are not Drupal-specific.

Drupalize.Me resources

Posted on Tuesday, April 21, 2015 - 08:10 by joe

Here's an example of an assumption; The sun will rise tomorrow. An assumption is something that is accepted as true or as certain to happen, without proof. This kind of thinking, while convenient, is prone to concealing facts, and troublesome when debugging code. This article defines what an assumption is, and provides some techniques for helping to eliminate them during debugging.

Posted on Thursday, May 14, 2015 - 08:02 by joe

Debugging is a discipline that requires patience, and a fervent attention to detail. In the often times fast paced world of software development, when we're faced with deadlines, and an ever growing list of new features to add, and bugs to resolve, it can be a difficult to slow down and proceed in a meticulous, measured fashion. When it comes to solving difficult problems though, this fastidious approach is exactly what's required to locate, and resolve, a problem's root cause.

Posted on Tuesday, August 3, 2021 - 08:52 by joe

Being able to execute, and step debug, Drupal's test using the PhpStorm UI makes it easier and more efficient to write tests for your projects. Learn how to configure PhpStorm to run Drupal's PHPUnit tests inside of a DDEV environment using docker-compose and a remote PHP CLI Interpreter. This setup will work for both Drupal core and your custom code.

Drupal 8, 9, and 10
More information

Knowing how to clear Drupal's cache is an important skill for any developer. You'll likely find yourself doing it frequently in order to get Drupal to register the changes you make to your code, or other updates you make via the UI. It is also a good first step to trouble shooting problems with your Drupal site: Clear the cache before you do any other debugging to ensure it's not just a bad cache entry.

More information

Making Drupal fast by default implies having caching layers and CSS and JavaScript aggregation utilities enabled out-of-the-box. As a theme developer this can be annoying, because you must clear these various caches in order to preview any changes. In addition, inspecting variables with debugging tools often produces PHP errors. We'll make some recommendations for PHP settings on your local environment that can prevent these errors from happening so often.

By the end of this tutorial, you should be able to:

  • Set up your local Drupal site for theme development
  • Prepare your local development environment for working on and debugging themes

Stark is one of the themes bundled with Drupal. It is intentionally bare bones and its purpose is to help Drupal theme and module developers get to the heart of Drupal's system templates.

Drupal 8, 9
More information

Stark is one of the themes bundled with Drupal. It is intentionally bare bones and its purpose is to help Drupal theme and module developers get to the heart of Drupal's system templates. In this tutorial, we'll explore Stark and its primary features and discuss the various reasons for utilizing the Stark theme.

More information

In this tutorial, we'll continue to look under the hood of Drupal 8, this time using a tool bundled with Devel called Webprofiler. You'll learn how to use the web debug toolbar and the profiler. You'll also learn how to reverse engineer a page to find out the names of the controllers responsible for output on that page.

Note: Webprofiler is now a separate project from Devel but still has it as a dependency.

Note: In order to get the Webprofiler timeline view working you need to add some configuration to your settings.php file. See the file included with the Webprofiler module for more information on how to do this.

Additional resources

Webprofiler project on

More information

In this tutorial we're going to use the git bisect command to do a little bit of debugging. We're all human, and sometimes bugs get introduced our software and we may not notice them for a while. Especially on fast moving projects. A good example of this would be a performance regression, and now you want to figure out what commit made everything run slower all of a sudden. Bisect allows us to do a binary search between a known good commit and a known bad commit and quickly narrow down which commit introduced the problem. From there it's much easier to figure out what exactly the problem is and fix it.


Drupal 7, 8, 9, and 10
More information

Devel is a popular developer module containing a variety of developer and debugging utilities including Webprofiler, Devel generate and Kint.

More information

Debugging your Drupal codebase can be made substantially easier by learning how to enable and configure the Xdebug PHP extension.


Not sure where to start? Our guides provide useful learning tracks for all skill levels.

Navigate guides

External resources

  • Devel (
    • The Devel module, and its many sub-modules, provide useful tools for debugging, and understanding, Drupal code.
  • Xdebug (
    • Xdebug is a PHP extension, and the tool of choice, for setting breakpoints and stepping through PHP code as it is executed.
    • Our recommendation: bite the bullet and figure out how to use Xdebug; it’ll save time and make you a better developer.
  • Drupal 8 Debugging Techniques (
    • Experienced Drupal developer Ivan Zugec demonstrates various Drupal debugging tools including Kint, Webprofiler, Xdebug, Drupal Console, and more. Includes live demonstrations that’ll give you a good idea of each tool’s functions.
  • Dark Art of Debugging - php[tek] (
    • This presentation from php[tek] by our own Joe Shindelar lays out a tools-independent approach for methodically locating bugs in software. Useful for practicing and getting better at debugging.
  • Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems, by David J. Agans (
    • A book that teaches how to approach debugging using methodical analysis in order to be a more efficient and better developer.