--- url: 'https://metadrop.net/en/articles/what-you-need-know-enabling-state-cache-drupal-103' title: 'What you need to know before enabling the state cache in Drupal 10.3' author: 'Eduardo Morales' date: '2024-10-11T07:23:20+00:00' updated: '2026-06-04T07:44:11+00:00' type: article summary: "State Cache, Drupal 10.3.0 introduces a new improvement in the handling of the State API, before enabling it, we'll tell you the keys to ensuring that the site's performance is optimized and there are no issues with the new configuration." tags: - 'Drupal Planet' image: 'https://metadrop.net/sites/default/files/styles/full/public/2024-10/drupal-cache-flag-not-set.png.webp?itok=hy6dbu9F' published: true og: determiner: Automatic site_name: Metadrop 'image:url': 'https://metadrop.net/sites/default/files/styles/full/public/2024-10/drupal-cache-flag-not-set.png.webp?itok=hy6dbu9F' 'image:type': image/png 'image:width': '492' 'image:height': '464' 'image:alt': 'What you need to know before enabling the state cache in Drupal 10.3' street_address: 'Calle Manuel Luna, 12, 3 Dcha' locality: Madrid region: Madrid postal_code: '28020' country_name: España email: hola@metadrop.net phone_number: '910053180' schema: '@context': 'https://schema.org' '@graph': - '@type': Article '@id': 'https://metadrop.net/en/articles/what-you-need-know-enabling-state-cache-drupal-103#article' name: 'What you need to know before enabling the state cache in Drupal 10.3' headline: 'What you need to know before enabling the state cache in Drupal 10.3' description: "State Cache, Drupal 10.3.0 introduces a new improvement in the handling of the State API, before enabling it, we'll tell you the keys to ensuring that the site's performance is optimized and there are no issues with the new configuration." image: '@type': ImageObject url: 'https://metadrop.net/sites/default/files/styles/full/public/2024-10/drupal-cache-flag-not-set.png.webp?itok=hy6dbu9F' width: '492' height: '464' datePublished: '2024-10-16T09:23:21+0200' dateModified: '2026-06-04T09:44:11+0200' author: '@type': Person name: 'Eduardo Morales' publisher: '@type': Organization '@id': 'https://metadrop.net/#organization' mainEntityOfPage: 'https://metadrop.net/en/articles/what-you-need-know-enabling-state-cache-drupal-103' - '@type': Organization '@id': 'https://metadrop.net/#organization' url: 'https://metadrop.net/' name: Metadrop sameAs: - 'https://www.drupal.org/metadrop' - 'https://twitter.com/metadrop' - 'https://asociaciondrupal.es/partner/metadrop' - 'https://www.linkedin.com/company/metadrop' logo: '@type': ImageObject url: 'https://metadrop.net/themes/custom/mdrop_radix/logo-metadrop-500-500.jpg' width: '500' height: '500' - '@type': ItemPage '@id': 'https://metadrop.net/en/articles/what-you-need-know-enabling-state-cache-drupal-103' breadcrumb: '@type': BreadcrumbList itemListElement: - '@type': ListItem position: 1 name: Home item: 'https://metadrop.net/en' - '@type': ListItem position: 2 name: 'Expert Drupal & Tech Articles' item: 'https://metadrop.net/en/articles' publisher: '@type': Organization '@id': 'https://metadrop.net/#organization' --- 1. [Articles](https://metadrop.net/en/articles) # What you need to know before enabling the state cache in Drupal 10.3 Wednesday, October 16, 2024 State Cache, Drupal 10.3.0 introduces a new improvement in the handling of the State API, before enabling it, we'll tell you the keys to ensuring that the site's performance is optimized and there are no issues with the new configuration. You have likely upgraded Drupal to version 10.3.0 and noticed a new message in the reports regarding the State Cache: The message reads as follows: > The State Cache flag $settings\['state\_cache'\] is not enabled. It is recommended to enable it in settings.php unless too many keys are stored. Starting with Drupal 11, State Cache will be enabled by default. ## What is the State API? Let's begin by understanding what the State API is. The State API in Drupal is a system that allows the storage and retrieval of small data fragments that are necessary for site operation but are not part of the overall configuration. Unlike the Config API, which focuses on data that must be consistent across different environments (like production, development, etc.), the State API is intended for environment-specific data that can change more dynamically and do not need to be synchronized across different environments. ## Why does it need to be cached? Currently, **State API** entries are stored in the **'key\_value' table**. If you have never seen this table, it is a generic and flexible key-value store widely used in Drupal for multiple data storage purposes, a large catch-all box. This means that **the table is not optimized for access and reading**. The main change is that `\\Drupal\\Core\\State\\State` now extends `\\Drupal\\Core\\Cache\\CacheCollector`. This means that the most queried State API elements can be retrieved more efficiently from the cache instead of frequently querying the database. This is particularly beneficial for high-traffic sites where efficiency is key to maintaining optimal performance. ## What if we move the entire key\_value table to the cache? Depending on the system we use, the size dedicated to the cache may vary and is limited; intensive use may degrade the site's performance, hindering the retrieval of truly necessary information. Drupal's State API is designed to handle small data fragments that need frequent access and do not change consistently across environments. For example: - **Maintenance** flag: Enable site maintenance. - Last **cron** execution: Date and time of the lastest cron execution. - Data to optimize **route** queries: Information used to improve routing. However, certain cases are not optimal for the State API. For example, a development `flag` accessed only during a container rebuild should be avoided, such as twig debugging. Instead, the `key\_value` service should be used for large or infrequently accessed information with its appropriate collection. ## So, would enabling the State cache be enough for my needs? Drupal provides the option to configure the State API cache to prevent issues in existing sites with many or large entries; this feature must be explicitly enabled using the configuration flag: ```php $settings['state_cache'] = TRUE; ``` This ensures that the site takes advantage of the new cache functionality. If not explicitly set, Drupal will display the warning message mentioned at the beginning. It is important to note that [in Drupal 11+, the state cache is permanently enabled](https://www.drupal.org/node/3443018), eliminating the option to configure this flag. ## How do I know if I should enable it? Before activating this option, you need to check the current usage of the State API; this can be done using the following database query: ```sql SELECT COUNT(*), SUM(LENGTH(value)) FROM key_value WHERE collection = 'state'; ``` If the environment has more than 100 entries or a total value size over 100,000, you should consider reviewing and optimizing specific entries. Use the following query for more details: ```sql SELECT name, LENGTH(value) FROM key_value WHERE collection = 'state' ORDER BY LENGTH(value) DESC LIMIT 100; ``` ## What do I do with entries that are too large or do not fit the State API? As we have mentioned, the State API entries so far were stored in the 'key\_value' table. If you want to keep them, you can change the collection they belong to by replacing the State API service with the 'key\_value' one. ## Conclusion This change significantly improves the efficiency and performance of Drupal sites by optimizing the handling of state elements through caching. Although most developers won't need to make changes to their code, it's crucial to review the site configuration to ensure these new capabilities are adequately utilized. Optimizing queries and the cache structure can provide substantial benefits to the end-user's experience and server resource management. **Documentation:** - [Change record - State service now uses a cache collector for performance](https://www.drupal.org/node/3177901). - [State API Documentation](https://www.drupal.org/docs/develop/drupal-apis/state-api/state-api-overview) - Eduardo Morales Senior Drupal developer [Drupal Audit Services](https://metadrop.net/en/services/drupal-audit " See Drupal Audit Services") Independent web audits for accessibility, SEO, performance, security and UX — on Drupal or any platform. Get a prioritised, actionable fix plan with estimated effort. See more