Last updated December 16, 2021

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

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.

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.

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-Local environment using docker-compose and a remote PHP CLI Interpreter. This setup will work for both Drupal core and your custom code.


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.


More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • Devel (
    • The Devel module, and its many sub-modules, provide useful tools for debugging, and understanding, Drupal code.
  • Drupal Console (
    • The Drupal Console command line application has a number of helpful debug:* commands. It's particularly useful for introspecting a specific Drupal site.
  • Xdebug (
    • Xdebug is a PHP extension, and the tool of choice, for setting breakpoints and stepping through PHP code as it is executed. Download from
    • 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.
  • Become a Better Developer with Debugging Techniques for Drupal (
    • This webinar provides some good advice on where and what to look for when debugging. It's useful for any developer, but especially relevant given its Drupal context.
  • 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.