Use Drush to Recover a Drupal Site Crashed by Deleting a Field

It was late last night. I was working on my custom B2B project, KingChefs.com, which is hosted on a cloud VPS (with its web root at /var/www/html/kingchefs.com). Everything was running smoothly. I was in the middle of a database cleanup, ruthlessly pruning old configuration baggage.

I went into the Drupal administrative UI and deleted a legacy field in the Additional Business Location content type: field_is_primay_location. Since I had recently reconstructed the Business Location content type into Additional Business Location, this specific field had become completely obsolete. My plan was simple: delete the field, let Drupal purge the database tables, and rebuild the cache.

But Drupal did not complete these tasks as I had hoped. Instead, a fatal error crashed the system, leaving me with a completely blank page—the dreaded White Screen of Death (WSOD).

Tracing the Error

I immediately connected the dots: deleting that legacy field had triggered the disaster. Before executing the deletion, Drupal's administrative UI had warned me by displaying a list of configurations that would be updated or removed as a consequence. At the time, I didn't grasp the true severity of the warning, assuming Drupal’s active configuration manager would handle the cleanup gracefully. I never expected a simple field deletion to bring the entire platform down so spectacularly.

Drawing on years of Drupal troubleshooting experience, I reasoned that running pending database updates or forcing a cache clear might untangle the mess. However, attempting to access the update.php script via the browser was entirely useless—the WSOD blocked my entrance completely.

With the web UI dead in the water, my only remaining line of defense was the CLI. It was time to log in via SSH and let Drush do the heavy lifting.

I fired up the terminal and ran:

/var/www/html/kingchefs.com$ sudo -u www-data ./vendor/bin/drush cr

Instead of a clean, green success message, my console spat out a wall of red error text:

[error]  Drupal\search_api\SearchApiException while adding Views handlers for field Content » Reverse reference: Primary Location on index Partner Index: Could not retrieve data definition for field 'Reverse reference: Primary Location' on index 'Partner Index'. in Drupal\search_api\Item\Field->getDataDefinition() (line 487 of /var/www/html/kingchefs.com/web/modules/contrib/search_api/src/Item/Field.php). 

In Field.php line 487:
                                                                                                                
  Could not retrieve data definition for field 'Reverse reference: Primary Location' on index 'Partner Index'.

Why Did it Break?

Looking at the stack trace, the culprit was immediately clear.

While Drupal Core’s field purging system is excellent at safely dropping database tables (such as node__field_is_primay_location) behind the scenes, it does not automatically clean up configuration dependencies inside contributed modules—especially robust ones like Search API.

My search index (Partner Index) still held a stale reference mapped to the now-deleted field. During the cache rebuild, Search API’s Views integration attempted to load the metadata (Data Definition) of this missing field. Finding nothing but an empty reference, it threw a fatal SearchApiException. Because this exception occurred during the bootstrap of the Views data cache, the entire routing system locked up. This meant the Admin UI was completely inaccessible, leaving me unable to remove the field through the standard backend.

How to Recover: Directly Editing Active Config via CLI

To get the site back online, I had to bypass Drupal's broken backend UI entirely and perform surgery on the active configuration database directly using Drush.

Here is exactly how I resolved it in four steps:

Step 1: Finding the Config Key

First, I ran a status check to determine the exact machine name of my target search index:

/var/www/html/kingchefs.com$ sudo -u www-data ./vendor/bin/drush config:status | grep search_api.index

This command returned three active indexes, including our target: search_api.index.partner_index.

Step 2: Opening the Config Editor

Next, I fired up Drush's interactive configuration editor targeting this specific index:

/var/www/html/kingchefs.com$ sudo -u www-data ./vendor/bin/drush config:edit search_api.index.partner_index

This immediately opened the active, live YAML configuration in my system's default terminal text editor (Vim), completely bypassing the broken PHP rendering layer.

Step 3: Removing the Stale YAML Block

Inside Vim, I searched for "Primary Location" and found the orphaned mapping block nested under the field_settings section:

field_is_primary_location:
    label: 'Reverse reference: Primary Location'
    datasource_id: 'entity:node'
    property_path: 'search_api_reverse_entity_references_node__field_business_partner:field_is_primary_location'
    type: boolean

I carefully deleted this entire block (including the key name and all indented properties beneath it). In Vim, I pressed Esc and typed the standard save-and-exit command: :wq!.

Immediately upon exit, Drush prompted me in the terminal:

Do you want to import the changes? (yes/no) [yes]:

I typed y (yes) and pressed Enter to import the patched configuration directly into the active database.

Step 4: The Glorious Green Success

With the stale, broken configuration successfully pruned and imported, I initiated the cache rebuild once more:

/var/www/html/kingchefs.com$ sudo -u www-data ./vendor/bin/drush cr
 [success] Cache rebuild complete.

In just two seconds, the console compiled flawlessly, and the entire KingChefs.com site was back online!

Lesson Learned: The Ultimate SOP for Deleting Fields in Drupal

If you are running a highly configured, search-indexed Drupal directory, deleting a field directly through the UI without proper preparation is a high-risk gamble. To ensure 0% downtime during database pruning, always adhere to this strict Reverse-Cleanup SOP:

Prune Views Dependencies: Check all your Views. If the field is used as a Field, Filter, Sort, or Contextual Filter, remove those references and save the Views first.
Remove from Search API Indexes (The Lifesaver): Navigate to /admin/config/search/search-api/index/[index_id]/fields first. Uncheck the field from the index, and save the configuration.
Clean Custom Code & Metatags: Search your custom .module files, theme .theme scripts, and Twig templates for the field's machine name (e.g. field_is_primay_location) and remove them. Clear any Metatag token mappings.
Execute Deletion: Only when the field has been completely decoupled from all views, indexes, and custom code should you navigate to Manage fields and click Delete.

Final Thoughts

In this era of rapid AI-generated content and easy automation, we are constantly told to "move fast and break things." However, building a highly resilient, high-value digital asset like KingChefs.com requires deep architectural discipline and meticulous engineering.

By maintaining a clean separation of concerns and keeping our databases and configurations perfectly in sync, we protect our sites against data entropy and build systems that can scale infinitely.

Finally, if your Drupal UI crashes again (which, let's face it, is almost a guarantee in a developer's journey), do not despair. Never give up on your site—look beyond the web interface, embrace the power of the command line, and let CLI tools like Drush do the magic.

Have questions about Search API indexing or advanced Drush configurations? Let's discuss in the comments below!