Debugging Drupal 500 Errors by Following the Render Pipeline

A Drupal 500 response tells you where the request ended, not where the failure began. The fastest diagnosis comes from dividing the request into routing, controller or data work, render-array processing, Twig, and final response delivery. Evidence from each layer is more useful than changing several settings at once.

Compare rendered and non-rendered routes

Test more than one route. If an RSS, JSON, or other direct response succeeds while normal HTML pages fail, the database and router may be healthy and the problem is likely in rendering or theming. If every route fails, begin earlier in bootstrap, services, or configuration. This comparison turns a broad outage into a smaller hypothesis.

Read the most specific exception

Drupal’s recent log messages and the PHP error log should identify the exception class, file, and first relevant stack frame. Temporarily increase development logging only in a non-production environment, reproduce one request, and restore normal logging afterward. Work from the newest error so earlier experiments do not distract from the current failure.

Change one boundary at a time

Verify the route, then controller output, then render arrays, attached libraries, theme registry, and Twig templates. Rebuild caches after changes that affect services, routes, extensions, or templates. Retest the same small route set after every change so success is attributable to one correction.

Working example

drush watchdog:show --count=10 --extended
drush cache:rebuild
drush status

Key Takeaways

• Compare HTML with direct-response routes to locate the failing layer.
• Use the newest exception rather than the generic browser message.
• Change and verify one application boundary at a time.

Further Reading

• Drupal logging and errors
• Drupal API documentation