Last Reviewed: 2026-04-21

Using Solr 8 and Solr 9 on Drupal

Information on using Pantheon Search with Solr 8 and Solr 9 on Drupal, including setup, upgrade, and troubleshooting

Discuss in Slack

Edit this page on GitHub Report an issue with this doc

Pantheon Search gives Drupal web teams a high-performance search index integrated with Integrated Composer's one-click updates. Pantheon Search supports both Apache Solr 8 and Solr 9. Solr 9 builds on the foundation of Solr 8 with improved performance, more secure defaults, and new search capabilities.

Solr Features

For more information, refer to the Drupal Search API Solr documentation.

Custom Processors

Search API module processors provide a variety of configuration options for your Pantheon Search results, like boosting results based on dates, taxonomy terms, or specific content types, controlling access to content based on permissions, and adding highlighted excerpts to results.

Refer to the Search API module processors documentation for details.

Before You Begin

Drupal Site Setup

Pantheon Search with Solr can be used on Drupal sites. You can set up a new Drupal site or visit the Drupal upgrade and migration guide to create a Drupal site.

Prepare the Local Environment

Ensure you review our documentation on Git, Composer, and Terminus, and have them installed and configured on your local machine. Pantheon requires Composer 2 at a minimum.

• Mac users can use Homebrew to install Git, Composer, and PHP, along with their required dependencies. Restart the shell or terminal environment after entering the following command:

• Windows users should install the following dependencies:

  • Composer

  • Git

  • The XAMPP development environment or a similar package might need to be installed to satisfy some dependencies.

Enable Pantheon Search

Enable Pantheon Search under Settings in your Pantheon Site Dashboard. This feature is available for sandbox sites as well as paid plans at the Professional level and above.

Using the Site Dashboard

1. Navigate to the site and environment you would like to configure.

2. Click Settings.

3. Click Add Ons > Apache Solr: Add.

Using Terminus

Enter the following command. Replace $SITE with the specified name of the site:

Configure the Solr Version

Add or update the following in your pantheon.yml file before installing the Drupal search module to avoid incompatibilities.

Push the changes to pantheon.yml. A confirmation message is returned in Git, which is also visible in the Site Dashboard's commit history within Code tab. The pantheon.yml file follows code through environments as you promote it, enabling the Solr server in each environment automatically.

For more information, refer to the documentation on Specifying a Solr version.

Install the Search API Pantheon Module

Composer automatically installs the following dependencies when you install drupal/search_api_pantheon:

• Solarium — a Solr client library for PHP.
• Search API — Drupal's module for indexing content entities.
• Search API Solr — connects Search API to Apache Solr. Version 4.3.x or later is required for Solr 9 compatibility.

1. Clone the Git repository for the desired environment from the Pantheon Site Dashboard.

2. Enter the following command in the terminal to run composer install:

3. Add the Search API Pantheon module as a required dependency:

4. You should now have the Search API Pantheon module installed along with its dependencies. You can run git status to verify that only composer.json and composer.lock were modified.

5. Commit and push the changes, Integrated Composer will take a few moments to install these on your site.

1. Run git status to verify that only composer.json and composer.lock were modified.
2. Commit and push the changes. Integrated Composer will take a few moments to install these on your site.

Enable the Search API Pantheon Module

Navigate to Admin > Extend (/admin/modules) and enable Search API Pantheon. Enabling this module also enables Search API and Search API Solr if they are not already enabled.

You can also enable it from the command line using Terminus and Drush replacing $ENV with the environment:

Verify the Installation

Navigate to Configuration > Search & Metadata > Search API in the Drupal Admin interface. Confirm that the Pantheon Search server and Primary index exist and are enabled.

Configure Pantheon Search

When you enable the Search API Pantheon module, a default Primary index is automatically created and linked to the Pantheon Search server. You can use this index or create a custom one.

Add Search Index

Navigate to Configuration > Search & Metadata > Search API within Drupal's Admin interface. The server labeled Pantheon Search should be displayed with an enabled status.

Using the Primary Index: Select the Primary index to use the default index automatically created when the module was enabled.

Creating a Custom Index:

1. Click Add Index.
2. Give the index a name and select a datasource. If this is your first time using Search API, select Content to index your site's nodes.
3. Select Pantheon Search as the Server.
4. In the Index Options panel, ensure Index items immediately is checked.
5. Click Save to add the new index.

The Index status page should indicate that the newly created index was successfully saved.

Add Fields to the Index

1. Click the Fields tab and click Add fields.
2. Add the fields you want to search, such as Title and Body.
3. Click Save changes when you are finished.

Post the Schema

Post the schema to the Solr server before indexing content:

The [path] argument is optional. Provide it only if you want to use a custom config set directory. If omitted, the default config set matching the installed Search API Solr version is used.

Index Content

1. Click Index now on the View tab of your index's Overview page to populate the index with your content. Content will also be indexed automatically when cron runs.
2. Click Search API to return to the Search API overview page at admin/config/search/search-api.

Both the server and index you just created should be displayed on the page.

Upgrading from Solr 8 to Solr 9

Update the module before switching pantheon.yml. This order ensures the correct Solr 9 schema and connector are in place before Pantheon provisions the new Solr 9 server.

1. Update the module:

2. Update your pantheon.yml:

3. Clear the cache:

4. Post the schema for the new Solr version:

   Wait a few minutes for the platform to provision the new Solr 9 core. Verify the core is ready by running the diagnose command or checking the server status page (admin/config/search/search-api > Pantheon Search), then post the schema:

5. Clear the index and reindex content:

   After switching Solr versions, Drupal's index tracker may still show items as indexed from the old core. Running drush search-api:clear resets the tracker and queues all content for reindexing, which is processed when drush search-api:index runs.

6. Test search functionality thoroughly on non-production environments. Use terminus drush $SITE.$ENV -- search-api-pantheon:diagnose to verify the configuration.

Rolling Back to Solr 8

For some reason if you need to revert to Solr 8 after upgrading, the search_api_pantheon 8.5.x module supports both Solr 8 and Solr 9, so you do not need to downgrade the module version.

1. Change pantheon.yml back to version: 8:

2. Commit and push the change:

3. Clear the cache:

4. Re-post the Solr 8 schema:

5. Clear the index and reindex content:

Upgrading from 8.4.x to 8.5.x

If you are upgrading from 8.4.x and want to continue using Solr 8, no migration is needed:

1. Update the module:

2. Clear the cache:

If you were previously running Search API Solr 4.2.x or earlier, you must also resolve a schema incompatibility. See Schema incompatibility with Search API Solr 4.3.x below.

Troubleshooting

Schema incompatibility with Search API Solr 4.3.x

Search API Solr 4.3.x introduced fundamental schema changes that are incompatible with indexes created by 4.2.x or earlier. This affects any site upgrading the module to 4.3.x, regardless of Solr server version. After upgrading, you may encounter the following error:

1. Post the updated schema:

2. Disable and re-enable the Solr server to clear all tracked index data:

   Find your <server_id> with terminus drush $SITE.$ENV -- search-api:server-list.

3. Reload the Solr core:

4. Wait at least 5 minutes, then verify the schema version has updated:

   The platform checks for new schemas and issues a core reload within 1-5 minutes.

5. Re-enable all indexes (they are automatically disabled when the server is disabled):

6. Reindex all content:

7. Verify search functionality is working as expected.

Incorrect Solr Version

This error is indicative of Solr 3 being active when Solr 8 is expected:

When running drush sapi-search commands, you may also see:

This can be fixed by updating pantheon.yml to use Solr 8.

Diagnose Issues

The diagnose command drush search-api-pantheon:diagnose (sapd) checks the Search API install and returns an error for any part that is not working.

The drush search-api-pantheon:select (saps) command runs the query against the Solr server. It is recommended that you use ?debug=true on any Solr page to allow a query to pass.

Deploy an Updated config.zip to your Solr Server

If the Search API Solr displays the following after the Search module is installed:

It is advisable to download and deploy an updated config.zip to your Solr server.

This message can safely be ignored. It resolves once a search index has been created and the schema files have been posted.

Fatal error: Cannot redeclare config_get_config_directory()

This error occurs after installing search_api_pantheon for Drupal using Composer. If you receive this error, you should switch to the Drupal Composer-managed Upstream. See Switch Your Custom Upstream for instructions on how to do this.