Config Doctor

Config Doctor finds the configuration problems that make deploys fail, and lets configuration imports fix themselves instead of stopping. It reports configuration nothing uses, finds missing, circular and undeclared dependencies before drush config:import runs into them, and can apply the decisions an administrator would otherwise make by hand when an import fails, the same way every time, with a snapshot and a log of every decision.

A failed drush cim or drush deploy usually means someone has to read the error, guess the cause and decide what to do: turn a module back on, keep a setting only this site has, delete a leftover block. Config Doctor shows those problems ahead of time and, if you switch the policy on, makes those decisions for you, in writing.

Built for government and regulated sites

On accredited systems every configuration change goes through change control. Config Doctor keeps that review small and on record:

• Less to review: the unused configuration report shows content types, fields, views, image styles, text formats, roles, blocks and menus nothing uses, so they can be removed instead of exported, deployed and reviewed forever.
• Every import decision on record: each adjustment the import policy makes is logged (its own log channel, so it can reach syslog and central log collection), with the snapshot taken before it.
• Snapshots kept off the web: before every adjusted import, all active configuration is saved to a private folder; public:// and anything inside the web root are refused, because a snapshot holds API keys too.
• Hold switch: drush config-doctor:hold on stops imports from dropping anything the site has, during an audit or an investigation.
• CI ready: drush config-doctor:deps exits with an error code while dependency problems exist, so a bad export can fail the build instead of the deploy.

What it does

• Unused configuration report: bundles with no content, fields never filled in, views with no display in use, image styles and text formats nothing uses, roles with no users, disabled blocks or blocks left for uninstalled themes, and empty menus, with the evidence for each. Report only.
• Configuration dependency report: configuration that needs a missing item, module or theme (core refuses the import), circular dependencies (imported silently, but deleting any item in the loop later never finishes), and configuration that uses another item without declaring it (applied in the wrong order, and a source of config drift). --fix declares the undeclared ones in the exported files; nothing is removed.
• Config imports that fix themselves: never uninstall a module or theme during an import unless the export lists it; keep configuration only this site has when it is protected or still has content; drop incoming configuration that can't exist, keeping the site's working copy. It plugs into core's own import pipeline (like Config Ignore and Config Split), so plain drush cim, drush deploy and the sync page all apply it once switched on. drush config-doctor:preflight shows what it would do; drush config-doctor:import runs it once with no prompts.
• Config import guide: how a config import runs, step by step, and what each kind of dependency problem does (and doesn't do) to it, with tested examples, inside the site's admin pages.

Getting started

1. Install and enable the module. Give the Administer Config Doctor permission to the people who deploy.
2. Open Reports » Config Doctor (/admin/reports/config-doctor), or run drush config-doctor:deps and drush config-doctor:unused.
3. Before the next deploy, run drush config-doctor:preflight. When you trust what it shows, switch the policy on per environment in settings.php: $config['config_doctor.settings']['import']['enabled'] = TRUE;

Requirements

Drupal 10.3 or later, or Drupal 11. No other modules or libraries. A private file system (or another folder outside the web root) for import snapshots. Drush 12.5 or later for the command-line tools (optional).

Documentation

Full documentation, including the config import guide: Config Doctor documentation.

Supporting this module

Bug reports, feature requests and patches are welcome in the issue queue.

Built by Easy Life Agents @ Global Web Methods

Originally built for DocSyntra by EasyLifeAgents via Claude Code.

More Modules

• Block List: Lists every block on the site by the module that provides it, core included, with a plain-English description of each block and every place it is used.
• Drupal Cleanup: Finds and safely removes the data a site leaves behind (orphaned index entries, moderation states, queue items, abandoned batches, old working files), with backups, a hold switch and an audit trail.
• Module Cleanup: Lists uninstalled or deleted modules with leftover transient data and allows the admin to delete any leftover data. A fix for the "Module 'module_name' has an entry in the system.schema key/value storage" error.
• NIST for Gov: Reports that check a Drupal site against NIST SP 800-53 Rev. 5 controls, starting with API keys, passwords and tokens stored in plain text.
• Permissions Table: Fixes the permissions table by keeping its header fixed at the top and its horizontal scrollbar fixed at the bottom.
• Recipe Filter: Adds a "Recipe Type" sidebar menu to the Project Browser Recipes page, the same way Module Filter builds a sidebar for the Modules page.
• Sentinel: Warns people about danger where they are: FEMA public alerts, National Weather Service alerts and FEMA flood zones, with a warning when a flood alert hits a high-risk flood zone.
• Uninstall Impact: Shows what uninstalling a module deletes, before you do it.