Troubleshooting Database Updates

Before troubleshooting database update issues, always back up your database and codebase.

If there are problems preventing safe execution of database updates, update.php will display an error.

Read the error message carefully to determine the issue.

Invalid Modules or Themes

Sometimes, update.php may report invalid modules or themes. This happens when a module or theme is listed in core.extension.yml but is missing or incompatible with the site.

To resolve this:

1. Ensure you haven't imported an incorrect version of core.extension.yml.
2. Diagnose further based on the specific error message shown.
3. Rerun update.php after resolving the issue.

Missing Module or Theme

1. Check if the module or theme folder exists in your codebase—look in [site-root]/modules and [site-root]/sites/all/modules.
2. If missing, download the module from Drupal.org, ensuring it's compatible with your Drupal version.
3. If the folder exists but is incomplete or corrupt, re-download and replace it with a clean copy.
4. If it’s a custom or third-party module (e.g., from GitHub), try to retrieve the original version.
5. As a last resort, you may edit core.extension.yml to remove the entry—but this can lead to other fatal errors.
6. After fixing the issue, rerun update.php.

Incompatible with Drupal Core Version

1. If update.php reports a module or theme is incompatible, determine your current Drupal core version via Reports > Status report.
2. Check the module’s .info.yml file for compatibility keys:

core: 8.x
core_version_requirement: ^8.8 || ^9

This means it's compatible with both Drupal 8.8+ and 9.

core_version_requirement: ^9

This means it's compatible only with Drupal 9.

core: 8.x

Only compatible with Drupal 8.

core: 7.x

Only compatible with Drupal 7.

3. Update Drupal core or the module/theme to compatible versions.
4. If no compatible version exists, restore from a backup.
5. Then rerun update.php.

Incompatible with Installed PHP Version

1. Check .info.yml for a line like:

php: 7.3

2. Option 1: Install a version of the module or theme that supports your PHP version.
3. Option 2: Change your PHP version to one compatible with the module.
4. Once PHP and the module are compatible, rerun update.php.