One of the best features of Drupal is configuration management. While it is reliable functionality, you can break it. I have broken it, and other developers have broken it. Fortunately, it should be an easy fix most of the time, if you know which ones broke.
With larger projects, it's easy to miss things, deploy may work in a local environment and even in a QA environment but might fail in a (pre-)live environment because of a large number of changes applied at once.
What I have learned so far:
- You can break it when enabling the module and trying to modify its configuration right afterward.
- You are applying partial changes to the non-existing configurations.
- You are manually modifying config files and making a typo, indenting it wrong, or missing part of it.
- Writing configuration into the wrong file.
- The config file used to import was empty.
- Git merge failures
- Installing the module throws an error in the middle of the process
How do I know when something is broken?
Usually, these things appear when opening the related page that tries to use that configuration, but it also may appear by taking the whole site (or admin side) down. It is also possible that there are no visible issues or some smaller weirdness with functionality.
If the module install had an error, then most likely there's a configuration missing.
Finding broken configuration
It can be tricky. The first thing to check are errors - are they referring to some ID so you can check that configuration specifically? It is possible to do a full export of the configuration and try to check files one by one or check directly on the database.
There is also the module Broken Config, which scans config entities, and if some entity fails to load, it's likely broken and will print it out.
Recovering
Multiple options are available to fix. Try first to re-import the configuration. If that fails, most likely deleting and then importing it again should work. Sometimes it is also possible to fix it manually by adding missing keys.
If the module had an error during the installation, you should try to resolve the error and then reinstall the module. Errors during the module installation could leave your system in an unreliable state.
Preventing
You can prevent issues in most cases.
Changes that you deploy should be fully applied to some pre-live environments to notice things and do some quick fixes.
Implementing code reviews is an idea to apply, which can help to spot issues earlier.
Code reviews should be applied and reviewer should check for:
- config file changes for out-of-scope changes
- Check configuration file paths inside update hooks (easy to confuse path config/install with config/optional).
- empty files
- files with invalid structure
- config name and the content of it are matching
- typos in update hooks
You should review GIT flow for improvements, for example, by comparing changes between the production and new release branch.
When installing new modules, pay attention to all messages the process is outputting.
