If you got a generic error in Drupal and are not sure why then it's time to enable Drupal Debug Mode options and error reporting.
This is not helpful :(
The website encountered an unexpected error. Please try again later.
This is really important for the backend as well as the frontend developers to see the full error on your screen while you are working because you might not know what is the exact issue with your Drupal site with just a generic error statement.
Drupal Backend Debug Options
Let's go through some Drupal Debug options for the backend.
1. Enable backtrace errors
In Drupal, there is a way to backtrace the error and display it in the message area. You can put the following code in your settings.local.php or settings.php whichever you are using.
$config['system.logging']['error_level'] = 'verbose';
This makes the development easier on local as it will show the backtrace of the error which you can debug now.
2. Enable Error message to display
For local Drupal development, you should always enable "Error message to display" options in the "/admin/config/development/logging" configuration. This will give you more information about the errors.
Twig Debug Options for Frontend
Now let's see how we can make frontend developer life easy by enabling Drupal Twig debugging options.
1. Enable Twig Debug Config
If you are a front-end developer and work around twig files to beautify the Drupal site then enabling the twig to debug configuration is a must.
You can enable this by copying the "sites/default/services.yml" file and renaming the new file to development.services.yml. Once you have the development.services.yml file you can just add a new twig debug parameter to it to enable the twig debugging and see the error information.
parameters:
twig.config:
debug: true
By enabling the twig config you will be able to find from which TWIG template file the HTML markup is coming.
Now you will also be able to see what the other twig template suggestions which will override the current template.
It will also let you know the theme in which the twig template file is located so that you don't start editing the wrong twig file.
2. Debug variables in Twig
Once you have enabled twig.config debug option now you can a variable in a structured format in the frontend by using a simple line of code in the Twig file.
{{ dump(my_variable) }}
3. Disable Twig cache
Once the Twig debug option is enabled then you can also enable auto_reload and disable twig cache.
You can read more about Twig debugging here.
parameters:
twig.config:
debug: true
auto_reload: true
cache: false
More configs you should change...
1. Disable CSS and JS aggregation on the local environment in Drupal 8 by uncommenting the below lines to settings.local.php.
$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;
2. Disable Drupal 8 render cache and dynamic page caching by uncommenting the below lines to settings.local.php.
$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';
3. If you are using the Drupal version greater than 8.4 then do add the following line in the settings.local.php file.s
$settings['cache']['bins']['page'] = 'cache.backend.null';
4. In the settings.local.php file uncomment the following line to enable the null cache service in Drupal 8.
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
Enable Drupal debugging with Drupal Console
If everything mentioned earlier is too much for you and you got access to Drupal Console then a single one-liner command can do the trick for you.
drupal site:mode dev
This Drupal console command will make changes in Drupal 8 configurations such as system.performance, views.settings, and system.logging to enable debugging. Command also makes changes to sites/default/services.yml file related to twig.config for frontend debugging.
And once you are done debugging the Drupal site you can revert all configurations back by running another command.
drupal site:mode prod
And the good part is this also rebuilds the cache at the end.
Conclusion
Debugging a Drupal site is not easy but with the right tools and tricks, you can make Drupal give you more information about the errors. And this information can help to debug the error better and faster.
NOTE: Make sure to clear the cache on your Drupal site after all the changes you have done for the local environment development.
WARNING: Make sure to not enable all these settings on the production site, unless you need to ;)