Drupal Troubleshooting Overview

Introduction

This section provides solutions to common issues encountered with Drupal sites, focusing on performance optimization and analytics tracking. Learn how to diagnose and fix issues specific to Drupal's caching system, BigPipe, and module ecosystem.

Common Issue Categories

Performance Issues

Drupal's powerful caching and rendering system can sometimes impact Core Web Vitals:

Largest Contentful Paint (LCP) - Slow page loading, large images, unoptimized resources
Cumulative Layout Shift (CLS) - Layout shifts from dynamic content, missing dimensions
First Input Delay (FID) - JavaScript blocking, heavy client-side processing

Tracking Issues

Analytics and marketing pixels may not work correctly due to:

Events Not Firing - Cache issues, JavaScript errors, BigPipe conflicts
Duplicate Events - Multiple tracking implementations
Data Layer Issues - Incorrect structure, missing data

Diagnostic Tools

Drupal-Specific Tools

1. Drush

# Clear all caches
drush cr

# Check module status
drush pm:list

# View watchdog logs
drush watchdog:show

# Generate database report
drush core:status

2. Devel Module

# Install Devel for debugging
composer require --dev drupal/devel
drush en devel devel_generate webprofiler -y

Features:

Variable inspection (dpm, ddm functions)
Query logging
Memory usage tracking
Event subscriber inspection

3. Web Profiler

Included with Devel module:

Performance waterfall
Database queries
Cache operations
Event listeners
Route information

Access at: /_profiler

Browser Developer Tools

Performance Tab:

Record page load
Identify bottlenecks
Measure Core Web Vitals

Network Tab:

View resource loading
Check for 404s
Verify tracking pixels
Analyze payload sizes

Console:

Check for JavaScript errors
Inspect dataLayer
Debug tracking events

External Tools

Google PageSpeed Insights

https://pagespeed.web.dev/

Core Web Vitals scores
Performance recommendations
Field data vs lab data

WebPageTest

https://www.webpagetest.org/

Detailed performance metrics
Waterfall charts
Video recording
Multiple test locations

GTmetrix

https://gtmetrix.com/

Performance scores
Video playback
Historical tracking

Common Drupal-Specific Issues

Issue: Changes not appearing after deployment

# Clear all caches
drush cr

# Or be more specific
drush cache:rebuild

# Clear specific cache bins
drush cache:clear css-js
drush cache:clear render

Issue: Tracking codes cached for authenticated users

// Add proper cache contexts
$build['#cache']['contexts'][] = 'user.roles';
$build['#cache']['contexts'][] = 'session';

BigPipe Conflicts

Issue: Scripts loading in wrong order

// Use html_head for critical scripts
$attachments['#attached']['html_head'][] = [
  [
    '#type' => 'html_tag',
    '#tag' => 'script',
    '#attributes' => ['src' => $script_url],
    '#weight' => -100,
  ],
  'critical_script'
];

Issue: Dynamic content causing layout shifts

// Disable BigPipe for specific pages
if ($route_match->getRouteName() === 'problem.route') {
  $attachments['#attached']['library'][] = 'core/drupal.bigpipe.disable';
}

Module Conflicts

Issue: Module versions incompatible

# Check module requirements
composer show drupal/module_name

# Update specific module
composer update drupal/module_name --with-dependencies

# Check for security updates
composer audit
drush pm:security

Issue: Module hooks firing in wrong order

// Use hook weights
/**
 * Implements hook_module_implements_alter().
 */
function mymodule_module_implements_alter(&$implementations, $hook) {
  if ($hook === 'page_attachments') {
    // Move our implementation to end
    $group = $implementations['mymodule'];
    unset($implementations['mymodule']);
    $implementations['mymodule'] = $group;
  }
}

Performance Optimization Checklist

Caching Configuration

// settings.php or settings.local.php

// Enable caching for anonymous users
$config['system.performance']['cache']['page']['max_age'] = 3600;

// Enable CSS/JS aggregation
$config['system.performance']['css']['preprocess'] = TRUE;
$config['system.performance']['js']['preprocess'] = TRUE;

// Enable render cache
$settings['cache']['bins']['render'] = 'cache.backend.database';

// Configure dynamic page cache
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.database';

Database Optimization

# Optimize database tables
drush sql:query "OPTIMIZE TABLE cache_bootstrap, cache_config, cache_container, cache_data, cache_default, cache_discovery, cache_dynamic_page_cache, cache_entity, cache_menu, cache_render;"

# Clear old cache entries
drush sql:query "DELETE FROM cache_bootstrap WHERE expire > 0 AND expire < UNIX_TIMESTAMP();"
drush sql:query "DELETE FROM cache_default WHERE expire > 0 AND expire < UNIX_TIMESTAMP();"

Image Optimization

# Install Image Optimize module
composer require drupal/imageapi_optimize
drush en imageapi_optimize imageapi_optimize_webp -y

# Configure image styles with WebP
# Admin → Configuration → Media → Image styles

CDN Integration

# Install CDN module
composer require drupal/cdn
drush en cdn -y

// settings.php
$config['cdn.settings']['status'] = TRUE;
$config['cdn.settings']['mapping']['domain'] = 'cdn.example.com';

Debugging Workflow

1. Identify the Problem

Check browser console for errors
Review Drupal logs: drush watchdog:show
Check server error logs
Test in incognito mode (bypass cache)

2. Isolate the Cause

Disable modules one by one
Test with default theme
Clear all caches
Check recent code changes

3. Test Fix

Implement solution in development
Clear caches: drush cr
Test functionality
Check for side effects

4. Deploy

Update configuration
Deploy code changes
Clear production caches
Monitor for issues

Performance Monitoring

Enable Performance Logging

// settings.php
if ($settings['environment'] === 'dev') {
  // Enable Twig debugging
  $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
}

File: sites/development.services.yml

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

Query Performance

# Enable query logging
composer require --dev drupal/devel
drush en devel -y

Navigate to: /admin/config/development/devel

✅ Display query log
✅ Display query execution time
✅ Display memory usage

New Relic Integration

// settings.php
if (extension_loaded('newrelic')) {
  newrelic_set_appname('Drupal Site', '', TRUE);

  // Add custom parameters
  if (function_exists('newrelic_add_custom_parameter')) {
    $current_user = \Drupal::currentUser();
    newrelic_add_custom_parameter('user_id', $current_user->id());
    newrelic_add_custom_parameter('user_roles', implode(',', $current_user->getRoles()));
  }
}

Security Considerations

Update Management

# Check for security updates
composer audit
drush pm:security

# Update Drupal core
composer update drupal/core-recommended --with-dependencies
drush updb -y
drush cr

Module Security

Only install modules from drupal.org
Review module permissions
Check last update date
Monitor security advisories

Configuration Security

// settings.php
// Disable error display in production
$config['system.logging']['error_level'] = 'hide';

// Restrict access to update.php
$settings['update_free_access'] = FALSE;

// Hash salt (change this!)
$settings['hash_salt'] = 'YOUR-UNIQUE-HASH-SALT';

Getting Help

Drupal Community Resources

Drupal.org Forums: https://www.drupal.org/forum
Drupal Slack: https://www.drupal.org/slack
Drupal Stack Exchange: https://drupal.stackexchange.com/
Issue Queues: Project-specific on drupal.org

Professional Support

Acquia
Pantheon
Platform.sh
Drupal agencies (find at drupal.org/drupal-services)

Debug Information to Collect

When seeking help, provide:

# Drupal status
drush core:status

# Module list
drush pm:list --status=enabled

# Recent logs
drush watchdog:show --count=50

# PHP info
drush php:eval "phpinfo();" > phpinfo.txt

# System requirements
drush core:requirements

Quick Reference

Essential Drush Commands

# Cache operations
drush cr                           # Clear all caches
drush cc css-js                    # Clear CSS/JS cache
drush cc render                    # Clear render cache

# Database operations
drush sql:dump > backup.sql        # Backup database
drush sql:cli                      # Open database CLI
drush updb -y                      # Run database updates

# Configuration
drush config:export -y             # Export configuration
drush config:import -y             # Import configuration
drush cex -y                       # Short form export
drush cim -y                       # Short form import

# Maintenance
drush watchdog:show                # View logs
drush cron                         # Run cron
drush core:requirements            # System status

Drupal Troubleshooting Overview

Drupal Troubleshooting Overview

Introduction

Common Issue Categories

Performance Issues

Tracking Issues

Diagnostic Tools

Drupal-Specific Tools

Browser Developer Tools

External Tools

Common Drupal-Specific Issues

Cache-Related Problems

BigPipe Conflicts

Module Conflicts

Performance Optimization Checklist

Caching Configuration

Database Optimization

Image Optimization

CDN Integration

Debugging Workflow

1. Identify the Problem

2. Isolate the Cause

3. Test Fix

4. Deploy

Performance Monitoring

Enable Performance Logging

Query Performance

New Relic Integration

Security Considerations

Update Management

Module Security

Configuration Security

Getting Help

Drupal Community Resources

Professional Support

Debug Information to Collect

Quick Reference

Essential Drush Commands

Topic-Specific Guides

Resources