Drupal Issues

Troubleshooting guide for Drupal-specific problems in the BlueFly.io platform.

Issue: White Screen of Death (WSOD)

Symptoms

Blank white page with no content
No error messages displayed
Site completely unresponsive
Admin pages also affected

Cause

PHP fatal error
Memory limit exceeded
Corrupted cache
Syntax error in custom module
Incompatible module update

Solution

# Enable error display temporarily
docker exec drupal php -d display_errors=1 -d error_reporting=E_ALL vendor/bin/drush cr

# Check PHP error logs
docker exec drupal cat /var/log/php/error.log | tail -100

# Increase memory limit
# In settings.php:
ini_set('memory_limit', '512M');

# Clear all caches
docker exec drupal vendor/bin/drush cr

# If cache clear fails, truncate cache tables
docker exec postgres psql -d drupal -c "TRUNCATE cache_bootstrap, cache_config, cache_container, cache_data, cache_default, cache_discovery, cache_dynamic_page_cache, cache_entity, cache_menu, cache_render, cache_toolbar CASCADE;"

# Disable recently updated module
docker exec drupal vendor/bin/drush pm:uninstall <module_name>

Prevention

Test updates in staging environment first
Implement error logging to external service
Set up monitoring for PHP errors
Use Git to track all code changes

Issue: Cache Rebuild Failure

Symptoms

drush cr hangs or fails
"Error: Class not found" messages
Container registry errors
Bootstrap failure

Cause

Circular dependency in services
Missing or invalid service definition
Corrupted container cache
File permission issues

Solution

# Delete container cache files manually
docker exec drupal rm -rf /var/www/html/web/sites/default/files/php

# Clear APC/OPcache
docker exec drupal php -r "opcache_reset();"

# Rebuild container from scratch
docker exec drupal vendor/bin/drush cr --no-class-loader

# If still failing, check service definitions
docker exec drupal php -r "print_r(yaml_parse_file('/var/www/html/web/modules/custom/*/services.yml'));"

# Verify autoloader
docker exec drupal composer dump-autoload

# Check file permissions
docker exec drupal chown -R www-data:www-data /var/www/html/web/sites/default/files

Prevention

Validate service definitions in CI/CD
Use PHPCS with Drupal coding standards
Test cache clears in CI pipeline
Document service dependencies

Issue: Module Installation Failure

Symptoms

"Requirements not met" error
Missing dependencies
Schema update failures
Module stuck in "installed" state

Cause

Missing PHP extensions
Incompatible Drupal core version
Missing module dependencies
Database schema conflicts

Solution

# Check requirements
docker exec drupal vendor/bin/drush pm:info <module_name>

# Install missing dependencies
docker exec drupal composer require drupal/<dependency>

# Force reinstall
docker exec drupal vendor/bin/drush pm:uninstall <module_name> -y
docker exec drupal vendor/bin/drush pm:install <module_name> -y

# Fix schema issues
docker exec drupal vendor/bin/drush updb -y

# Check for hook_requirements issues
docker exec drupal vendor/bin/drush php:eval "print_r(module_invoke('<module_name>', 'requirements', 'install'));"

Prevention

Pin module versions in composer.json
Test module installation in CI/CD
Document all PHP extension requirements
Use require-dev for development-only modules

Issue: Configuration Sync Errors

Symptoms

"Configuration has changed" error
UUID mismatch errors
Missing configuration dependencies
Import failures

Cause

Configuration edited in both code and database
UUID collision between environments
Missing configuration dependencies
Deleted configuration still referenced

Solution

# Check configuration status
docker exec drupal vendor/bin/drush config:status

# Export current configuration
docker exec drupal vendor/bin/drush config:export -y

# Import configuration with force
docker exec drupal vendor/bin/drush config:import -y --source=/var/www/html/config/sync

# Fix UUID issues
docker exec drupal vendor/bin/drush config:delete system.site
docker exec drupal vendor/bin/drush config:import -y

# Resolve dependencies
docker exec drupal vendor/bin/drush config:import --partial -y

# For stuck configs, delete and reimport
docker exec drupal vendor/bin/drush cdel <config.name>
docker exec drupal vendor/bin/drush cim -y

Prevention

Never edit configuration directly in production
Use config_split for environment-specific configs
Commit configuration exports after every change
Validate configuration in CI/CD pipeline

Issue: Database Update Failures

Symptoms

drush updb fails
"Allowed memory size exhausted"
Database timeout errors
Partial update completion

Cause

Large dataset migrations
Circular update dependencies
Memory/timeout limits
Locked tables

Solution

# Increase limits for updates
docker exec drupal php -d memory_limit=2G -d max_execution_time=0 vendor/bin/drush updb -y

# Run updates one at a time
docker exec drupal vendor/bin/drush updb --entity-updates
docker exec drupal vendor/bin/drush updb

# Check pending updates
docker exec drupal vendor/bin/drush updb:status

# Fix stuck updates (dangerous - backup first!)
# In drush console:
\Drupal::service('update.update_hook_registry')->setInstalledVersion('<module>', <schema_version>);

# For locked tables
docker exec postgres psql -d drupal -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE query LIKE '%<table>%' AND pid <> pg_backend_pid();"

Prevention

Test updates on copy of production database
Break large updates into batches
Monitor update duration in staging
Maintain database backups before updates

Issue: Entity Field Storage Errors

Symptoms

"Field storage definition not found"
Entity save failures
Missing field data
Schema mismatch errors

Cause

Field storage deleted but field still exists
Module uninstalled with orphaned fields
Database schema out of sync
Failed field migration

Solution

# Check field storage
docker exec drupal vendor/bin/drush php:eval "print_r(\Drupal::entityTypeManager()->getStorage('field_storage_config')->loadMultiple());"

# Rebuild entity definitions
docker exec drupal vendor/bin/drush entity:updates

# Delete orphaned field storage
docker exec drupal vendor/bin/drush php:eval "\Drupal\field\Entity\FieldStorageConfig::loadByName('<entity_type>', '<field_name>')->delete();"

# Purge deleted fields
docker exec drupal vendor/bin/drush field:delete-orphans

# Force sync entity schema
docker exec drupal vendor/bin/drush entup

Prevention

Use proper uninstall hooks
Test field deletions in staging
Implement field cleanup in CI/CD
Document field dependencies

Issue: Composer Conflicts

Symptoms

"Your requirements could not be resolved"
Package version conflicts
Plugin compatibility errors
Autoload failures

Cause

Conflicting package requirements
Outdated composer.lock
Platform requirements not met
Private package access issues

Solution

# Analyze conflicts
composer why-not drupal/<package> <version>

# Update specific package
composer update drupal/<package> --with-dependencies

# Clear Composer cache
composer clear-cache

# Regenerate lock file (last resort)
rm composer.lock
composer install

# Check platform requirements
composer check-platform-reqs

# For private packages, verify authentication
composer config --global --list | grep gitlab

Prevention

Use composer.lock in version control
Pin to specific versions, not ranges
Test Composer updates in CI/CD
Document platform requirements

Issue: Theme Rendering Errors

Symptoms

Twig syntax errors
Missing templates
Broken CSS/JS aggregation
Theme switching failures

Cause

Invalid Twig syntax
Missing template suggestions
Cache not cleared after theme changes
Asset compilation failures

Solution

# Enable Twig debugging
# In settings.local.php:
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
# In development.services.yml:
parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

# Clear theme cache
docker exec drupal vendor/bin/drush cr

# Rebuild theme registry
docker exec drupal vendor/bin/drush php:eval "\Drupal::service('theme.registry')->reset();"

# Check template suggestions
# Enable Twig debugging and view HTML source

# Rebuild assets
docker exec drupal vendor/bin/drush asset:rebuild

Prevention

Validate Twig templates in CI/CD
Use theme linting tools
Implement visual regression testing
Document template override patterns

Issue: REST/JSON API Errors

Symptoms

403 Forbidden on API endpoints
CORS errors
Serialization failures
Missing authentication

Cause

Permission configuration
CORS not configured
Entity access restrictions
Cache context issues

Solution

# Check REST resource configuration
docker exec drupal vendor/bin/drush config:get rest.resource.<resource_id>

# Verify permissions
docker exec drupal vendor/bin/drush role:perm anonymous | grep restful

# Enable CORS
# In settings.php:
$settings['cors'] = [
  'allowedOrigins' => ['*'],
  'allowedMethods' => ['GET', 'POST', 'PUT', 'DELETE'],
  'allowedHeaders' => ['Content-Type', 'Authorization'],
];

# Clear REST cache
docker exec drupal vendor/bin/drush cr

# Test API endpoint
curl -v -H "Content-Type: application/json" http://localhost/api/endpoint

Prevention

Document all API endpoints
Test API in CI/CD pipeline
Use OpenAPI specification
Implement API versioning

Back to Common Issues | CI/CD Issues

Drupal Issues

Drupal Issues

Issue: White Screen of Death (WSOD)

Symptoms

Cause

Solution

Prevention

Issue: Cache Rebuild Failure

Symptoms

Cause

Solution

Prevention

Issue: Module Installation Failure

Symptoms

Cause

Solution

Prevention

Issue: Configuration Sync Errors

Symptoms

Cause

Solution

Prevention

Issue: Database Update Failures

Symptoms

Cause

Solution

Prevention

Issue: Entity Field Storage Errors

Symptoms

Cause

Solution

Prevention

Issue: Composer Conflicts

Symptoms

Cause

Solution

Prevention

Issue: Theme Rendering Errors

Symptoms

Cause

Solution

Prevention

Issue: REST/JSON API Errors

Symptoms

Cause

Solution

Prevention

Related Documentation