This module focuses on identifying, debugging, and resolving common Drupal issues in a systematic and safe way. Acquia exams test whether you understand how Drupal fails, how to investigate problems, and which debugging tools or techniques are appropriate in each situation.
The key skill here is not guessing. It is following Drupal’s debugging workflow and choosing solutions that protect security, performance, and data integrity.
1. What Debugging Means in Drupal
Debugging in Drupal is the process of finding the root cause of a problem instead of masking symptoms. Drupal provides built-in tools and configuration options to expose errors in a controlled way.
Common categories of issues:
- White screen of death
- PHP errors and warnings
- Broken pages or layouts
- Incorrect data output
- Performance regressions
- Configuration issues
Acquia exam principle:
The safest debugging approach is always preferred over quick hacks.
2. Error Visibility and Environment Awareness
Development vs Production
Drupal must behave differently depending on the environment.
In development:
- Errors should be visible
- Debug output is acceptable
In production:
- Errors must be hidden from users
- Errors should be logged instead
Security implication:
Exposing stack traces or database errors in production can leak sensitive information.
Acquia exam trap:
Never enable verbose error output in production as a solution.
3. Enabling Error Reporting Correctly
Drupal error settings
Configuration location:
Configuration → Development → Logging and errors
Recommended settings:
- Development: Display all messages
- Production: Display none, log errors
Why this matters:
Drupal controls error output independently of PHP settings.
PHP error reporting
Drupal respects PHP error reporting but should not rely on ini changes alone.
Incorrect approach:
Editing php.ini directly on production servers to expose errors.
Correct approach:
Use Drupal configuration and logs.
4. Using the Drupal Log System
Database logging
Drupal logs errors, warnings, and notices using the logging system.
View logs at:
Administration → Reports → Recent log messages
Logging example:
$this->logger->error('Unexpected condition occurred');
Why this is correct:
- Keeps errors out of user-facing output
- Preserves security
- Allows post-incident analysis
Acquia exam trap:
Printing errors directly to the screen is almost always incorrect.
5. White Screen of Death
Common causes
- PHP fatal errors
- Missing modules or files
- Incorrect service definitions
- Syntax errors in custom code
Correct troubleshooting steps
- Enable error logging
- Check Recent log messages
- Review web server logs
- Disable custom modules if needed
Performance note:
A fatal error stops execution entirely and must be resolved before optimization.
6. Debugging Custom Module Issues
Step-by-step approach
- Identify when the issue started
- Check recent deployments or config changes
- Review custom module code
- Look for missing dependencies or services
Common mistakes
- Using \Drupal:: calls incorrectly
- Missing dependency injection
- Hardcoded configuration values
Acquia exam trap:
The correct answer often involves inspecting logs before changing code.
7. Debugging Configuration Issues
Symptoms
- Features not working
- Forms behaving unexpectedly
- Routes returning access denied
Common causes
- Missing permissions
- Incorrect YAML indentation
- Config not imported
YAML indentation example:
Incorrect:
requirements:
_permission: 'access content'
Correct:
requirements:
_permission: 'access content'
Why this matters:
YAML is whitespace-sensitive.
8. Using Devel and Development Tools
Devel module
Devel provides debugging helpers such as:
- Variable inspection
- Query logging
- Render array inspection
Usage example:
kint($variable);
Security note:
Devel must never be enabled in production.
Acquia exam trap:
Devel is for development environments only.
9. Debugging Render and Theming Issues
Common symptoms
- Missing variables in Twig
- Incorrect output
- Broken layouts
Correct techniques
- Use Twig debug mode
- Inspect render arrays
- Verify preprocess functions
Twig debug setting:
twig.config:
debug: true
Why this matters:
Twig debug reveals template suggestions and variables.
10. Debugging Access and Permission Issues
Symptoms
- Access denied errors
- Pages visible to wrong users
Correct checks
- Route permissions
- Entity access handlers
- User roles and permissions
Security implication:
Incorrect access logic can expose protected data.
Acquia exam trap:
Access issues are rarely solved by disabling security checks.
11. Debugging Performance Regressions
Common causes
- Disabled caching
- New custom code without cache metadata
- Excessive logging
Correct approach
- Compare before and after changes
- Check caching configuration
- Review recent code changes
Performance note:
Debugging performance starts with configuration, not code removal.
12. Real-World Debugging Scenarios
Scenario: Page suddenly shows blank screen
Correct steps:
- Check Recent log messages
- Enable error logging in development
- Inspect recent code changes
Scenario: Route returns access denied
Correct steps:
- Verify routing permissions
- Check user role permissions
- Confirm access callbacks
Scenario: Twig template not applied
Correct steps:
- Enable Twig debug
- Clear cache
- Verify template naming
13. How Acquia Tests Debugging Knowledge
Acquia focuses on:
- Logical troubleshooting order
- Safe debugging practices
- Drupal-native tools
They do not test:
- Low-level server debugging
- OS or network configuration
Final Exam Revision Checklist
- Errors logged, not displayed
- Logs checked before code changes
- Devel used only in development
- YAML indentation verified
- Cache cleared after changes
- Permissions reviewed carefully
One-Sentence Takeaway
Effective Drupal debugging follows a safe, structured process using Drupal’s built-in tools.
Quick Mental Checklist for Exam Questions
Is this safe in production
Where would Drupal log this
What changed recently
Is this config or code
What tool fits this issue