Theme debugging in Drupal is the process of identifying how markup is generated, which templates are being used, how variables are passed to Twig, and why expected changes are not appearing on the frontend. In Drupal 10 and 11, the rendering system relies heavily on render arrays, cache metadata, template suggestions, and preprocess logic. Understanding how these layers interact is critical for diagnosing frontend issues efficiently. Professional frontend engineers do not guess — they inspect template suggestions, review render arrays, check cache contexts, and validate preprocessing logic before making changes.

1. Enabling Twig Debug Mode

The first step in theme debugging is enabling Twig debug mode.

Edit:

sites/development.services.yml

parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

Then clear cache:

drush cr

Now inspect page source. You will see:

<!-- THEME DEBUG -->
<!-- FILE NAME SUGGESTIONS: -->

This shows:

• Which template is being used
• Available template suggestions
• File path of the active template

2. Understanding Template Suggestions

Drupal builds template suggestions automatically based on:

• Entity type
• Bundle (content type)
• View mode
• Path
• Node ID

Example suggestions for an Article node:

node--article.html.twig
node--1.html.twig
node.html.twig

If your override is not working:

• Confirm correct filename
• Confirm correct template directory
• Clear cache

3. Debugging Variables in Twig

To inspect available variables inside a template:

{{ dump() }}

Or inspect a specific variable:

{{ dump(content) }}

Note: Dump only works when Twig debug is enabled.

This helps identify:

• Field structure
• Render arrays
• Available attributes

4. Inspecting Render Arrays

Drupal does not pass raw data directly. It passes render arrays.

Example:

{{ content.field_image }}

Behind the scenes this includes:

• Formatter settings
• Access control
• Cache metadata

If output behaves unexpectedly, inspect the render array using dump().

5. Debugging Preprocess Functions

Templates receive variables from preprocess functions.

Example in weeklydrupal_theme.theme:

function weeklydrupal_theme_preprocess_node(&$variables) {
  $variables['custom_message'] = 'Frontend Debug Example';
}

Twig:

{{ custom_message }}

If variable does not appear:

• Check correct preprocess hook name
• Confirm cache cleared
• Confirm correct template is active

6. Cache Issues (Most Common Problem)

Common scenario:

"I updated template but nothing changed."

Checklist:

• Run drush cr
• Confirm Twig cache disabled (dev only)
• Check render cache contexts
• Confirm no reverse proxy caching (e.g., Varnish, CDN)

Enterprise environments often involve:

• Page cache
• Dynamic page cache
• CDN caching

Frontend debugging must consider all layers.

7. Debugging CSS and Library Loading

If styles are not loading:

Check:

1. weeklydrupal_theme.libraries.yml
2. Library attached in .info.yml
3. Browser network tab

Example library file:

global-styling:
  css:
    theme:
      css/style.css: {}

If CSS not applied:

• Confirm correct file path
• Clear cache
• Confirm library attached

8. Using Devel Module for Advanced Debugging

Install Devel module (development only):

drush en devel -y

Use:

{{ kint(content) }}

Kint provides structured output for deep inspection.

9. Common Theme Debugging Scenarios

Template override not working

• Wrong filename
• Wrong directory
• Cache not cleared

Field output not changing

• Using raw value instead of render array
• Formatter overriding output

Variable missing

• Preprocess not firing
• Wrong hook implementation

Markup correct but styling broken

• CSS not loaded
• Specificity issue
• Caching layer

Enterprise Debugging Mindset

Professional debugging approach:

1. Identify which template is used
2. Inspect available variables
3. Check preprocess layer
4. Validate render array
5. Confirm caching layer
6. Confirm asset loading

Never assume. Inspect and verify.

Interview Questions (Frontend Drupal)

1. How do you enable Twig debugging in Drupal?

Expected Answer:
Modify development.services.yml to enable debug, auto_reload, and disable Twig cache, then clear cache.

2. Why might a Twig template override not work?

Expected Answer:
Incorrect filename, wrong directory, caching not cleared, or suggestion not matching the active template.

3. What is a render array and why is it important in theming?

Expected Answer:
A render array is a structured array that contains markup, cache metadata, and access control. It ensures safe and cacheable output.

4. How do you debug variables available inside a Twig template?

Expected Answer:
Use {{ dump() }} or {{ kint() }} with Twig debug enabled.

5. What caching layers should be considered when debugging frontend issues?

Expected Answer:
Drupal page cache, dynamic page cache, render cache, and external layers like CDN or reverse proxy.

6. Where should you place logic if you need to prepare data for Twig?

Expected Answer:
Inside preprocess functions, controllers, or services — not inside Twig templates.