Diagnosing Drupal Fatal Errors After Deploy or Cache Rebuild

Recognizable Condition

After a code deploy, module enable, or drush cache:rebuild, users hit Drupal's generic error page — "The website encountered an unexpected error" — or a blank white screen. No stack trace appears unless error verbosity is temporarily raised. The issue may affect all users or only a subset, and it often coincides with a recent change to code, configuration, or infrastructure.

Assumptions

• Composer-managed Drupal 10/11 on Linux with PHP-FPM and MySQL or PostgreSQL
• Drush available on the server or via a deployment pipeline
• Configuration sync directory lives outside the webroot (e.g., ../config/sync)
• A staging environment mirrors production for safe reproduction

If any assumption is false, adapt the checks accordingly — for example, on Pantheon or Platform.sh, PHP-FPM restarts and file permissions are managed by the platform.

Cause and Diagnostic Quick-Reference

Ordered Diagnostic Checks

1. Reproduce and capture context. Note the exact timestamp, URL, HTTP method, and user role (anonymous, authenticated, admin). Open the browser dev tools Network tab to confirm a 500 or 200-with-empty-body response.
2. Read recent logs. On the server, check:
   

   # Drupal watchdog (dblog) via Drush
   drush watchdog:show --tail=50 --severity=error
   
   # PHP-FPM error log (path varies by distro)
   tail -n 100 /var/log/php-fpm/error.log
   
   # Syslog if Drupal logs there
   grep -i drupal /var/log/syslog | tail -20
   

   Run these as the deployment user or root. Look for PDOException, ContainerBuilder errors, or file_permissions warnings.
3. Check status report if admin UI reaches. Visit /admin/reports/status and /admin/reports/dblog. If the site returns a 500 on those paths too, skip to Drush.
4. Run Drush baseline.

   drush status
   # Verify Drupal root, DB connection, config sync path, and PHP version
   drush cache:rebuild
   # If this fails, the error output often pinpoints the cause

5. Validate configuration sync.

   drush config:status
   # Shows counts of new, changed, removed config objects
   drush config:import --diff --dry-run
   # Review the diff before committing

6. Inspect recent changes and permissions. Compare the deployed commit with the previous release. Verify file ownership:

   # Typical ownership for PHP-FPM user www-data
   ls -la sites/default/files/
   ls -la ../config/sync/
   stat -c '%U:%G' sites/default/files/private
   

Targeted Fixes Tied to Findings

Stale OPcache or Partial Container

If the error appears intermittently across requests, OPcache is serving stale bytecode. Fix:

1. Deploy atomically (symlink swap or rsync --delay-updates).
2. Restart PHP-FPM: systemctl reload php8.3-fpm (adjust version).
3. If opcache.validate_timestamps=0 (common in production), also clear OPcache via opcache_reset() in a post-deploy script or restart.
4. Run drush cache:rebuild.
5. Verify with repeated anonymous requests: for i in {1..10}; do curl -s -o /dev/null -w "%{http_code}\n" https://example.com/; done — all should return 200.

Risk: Restarting PHP-FPM drops active sessions. Schedule during low traffic or use a rolling restart if multiple workers exist.

Database Credentials or Connectivity

If logs show SQLSTATE[HY000] [2002] Connection refused or Access denied:

1. Confirm settings.local.php or environment variables inject correct $databases values.
2. Test connectivity: drush sql:connect should drop you into a MySQL/psql prompt.
3. Check grants: SHOW GRANTS FOR 'drupal_user'@'%';.
4. Clear caches after credential fix: drush cache:rebuild.

Risk: Editing settings.php directly on production is error-prone; use a secrets manager or deploy-time injection.

Configuration Mismatch

When drush config:status shows unexpected changes or core.extension differs:

1. Enable maintenance mode: drush state:set system.maintenance_mode 1 --input-format=integer.
2. Export current active config as a safety snapshot: drush config:export --destination=/tmp/pre-fix-config.
3. Review the diff from step 5 above. Resolve missing modules, UUID mismatches, or deleted config entities.
4. Run the import for real: drush config:import --diff.
5. Disable maintenance mode: drush state:set system.maintenance_mode 0 --input-format=integer.
6. Re-run drush status and drush cache:rebuild.

Risk: Config import can delete content types or fields if the exported config no longer references them. Always review --diff output and have a database snapshot.

File Permissions or SELinux

If logs show FileNotFoundException or Permission denied on file_private_path:

1. Ensure the PHP-FPM user owns writable directories:

   chown -R www-data:www-data sites/default/files
   chown -R www-data:www-data ../private
   chown -R www-data:www-data /tmp/drupal-private  # if custom tmp

2. Set directory permissions to 775 and files to 664 (avoid world-writable 777).
3. On RHEL/CentOS/Fedora, check SELinux contexts:

   ls -Z sites/default/files/
   # Should show httpd_sys_rw_content_t
   restorecon -Rv sites/default/files/

4. Verify $settings['file_private_path'] in settings.php points to an absolute path outside the webroot.
5. Retry drush cache:rebuild.

Risk: Over-permissive settings expose uploaded files to execution. Never set code directories writable by the web user.

Escalation Criteria

• Database/Infrastructure: Connection errors persist after credential and network validation, or monitoring shows saturated CPU, disk I/O, or storage full. Escalate to DBAs or hosting provider.
• Security: Logs reveal unexpected file writes in code directories, unknown admin accounts, modified hook_requirements() or hook_install(), or exploitation indicators (e.g., eval() in watchdog). Escalate to security team immediately; do not reboot or destroy evidence.
• Release Management: Config import cannot reconcile (e.g., UUID conflict on system.site), or the site remains down after all targeted fixes. Escalate to the release manager with a rollback plan — revert the deploy artifact, restore the database snapshot, and re-enable maintenance mode.

Verification After Fix

1. On staging with the same deploy artifact, clear caches and load anonymous pages from more than one PHP-FPM worker (use the curl loop above or a load-test tool).
2. Check /admin/reports/status — all requirements should show green.
3. Check /admin/reports/dblog — no new fatal entries during a normal smoke test (visit homepage, login, create a node, upload a file).
4. Run drush config:status and a diff import to confirm configuration is synchronized. Record the exact commands in your runbook.

Limitations and Notes

• This guide assumes Drush 12+ and Drupal 10/11. Drush command names differ in older versions (e.g., drush cr vs drush cache:rebuild).
• Do not enable verbose error display ($config['system.logging']['error_level'] = 'verbose') on production. Raise logging temporarily in settings.local.php only for the debugging window, then revert.
• Never run drush config:import or drush deploy:hook (which runs database updates) during live traffic without maintenance mode and a tested rollback path.
• If your hosting platform manages PHP-FPM (Pantheon, Platform.sh, Acquia), use their CLI tools (terminus, platform, acli) for restarts and log access instead of systemctl.