Like any other Drupal site, most troubleshooting issues with Drupal Starter Kits are around Drupal configuration, networking, or connectivity. The following are the known idiosyncrasies with Drupal Starter Kits, which will change and evolve over time.

Acquia DAM image styles do not apply to images in Drupal 10

When you use an Acquia DAM image style on an image in the WYSIWYG editor in Drupal 10, the image style does not apply to the image. This issue occurs because the Acquia CMS DAM embedded media template, also referred to as the Site Studio template, forces a specific image style regardless of the image style selected in the WYSIWYG editor.
To resolve this issue:

• Log in to the application as an administrator.
• Click Administration > Site Studio > Templates > Content Templates > Media.
• Expand the DAM - Media accordion and locate Embedded (Media, Image).
• Click the Edit menu corresponding to Embedded (Media, Image).
• Click the Reset button in the Edit menu.

• Open

  
• Click the Reset button in the resulting message box.

• Open

  
• Click Configuration > Content authoring > Text formats and editors.
  Alternatively, append /admin/config/content/formats to your application name.
• Save all the text editor formats:
  • Filtered HTML
  • Full HTML
  • Site Studio
• Visit the content page and verify the image styles.

Drupal-related errors

An error occurs because of non-existence of a Drupal module

The following error occurs when the system finds references of a module in the database but does not find it in the codebase:

[error] Error: the module {module_name} does not exist

This is a Drupal-related error. However, it can be triggered by Content Hub during import if the module in question is listed as a dependency but is missing from the subscriber.

For information about how to resolve this error, visit Fixing the error message "the module {module_name} does not exist".

Troubleshooting issues with Drupal Starter Kits upgrade

Indirect dependencies issues

When you run the composer update command to update Drupal Starter Kits, the system might not be able to update Drupal Starter Kits. The update command fails and the system displays the following error message:

To determine the root cause of the issue:

• Run the following command:

  copy

  composer why-not acquia/acquia_cms

  The system displays the following message:

  

  The message indicates that drupal/acquia_cms_starter restricts updating acquia/acquia_cms to the latest version.

• To check issues with the Drupal Starter Kits Starter module, run the following command:

  copy

  composer why-not drupal/acquia_cms_starter

  The system displays the following message:

  

• To check issues with all Drupal Starter Kits modules, run the composer why-not command for each module:

  

  You can locate indirect dependencies in the require section of the root composer.json file.

  

  Warning

  The require section in the composer.json file might be different for different users. Therefore, you must use your commands accordingly.

To resolve this issue:

• Remove all the indirect dependencies from the root composer.json file and run the composer install command.

  Alternatively, you can remove the indirect dependencies by running the following command:

  copy

  composer remove drupal/entity_clone drupal/acquia_cms_article
  drupal/acquia_connector drupal/acquia_search drupal/ctools drupal/entity_clone drupal/facets
  drupal/geofield drupal/google_tag drupal/jsonapi_extras drupal/metatag drupal/scheduler_
  content_moderation_integration

  

  

  For example, drupal/facets is a dependency of the Drupal Starter Kit Search module. Therefore, you must not have them in the root composer.json file. If they are included in the file, remove them manually or by running the following command:

  copy

  composer remove drupal/facets

• After removing all the indirect dependencies, update Drupal Starter Kits by running the following command:

  copy

  composer update acquia/acquia_cms

Minimum stability issues

If minimum stability blocks your Drupal Starter Kits upgrade, the system displays the following error message:

To resolve this issue:

• Update your root composer.json file by running the command:

  copy

  composer config minimum-stability dev

• Update Drupal Starter Kits to the latest version.

  • For Drupal Starter Kits 1.5.x or 2.x, run the following command:

    copy

    composer update acquia/acquia_cms -W

    

  • For Drupal Starter Kits composable architecture, run the following command:

    copy

    composer update drupal/acquia_cms* -W

How do I do X?

Drupal Starter Kits ship with a Tour page (/admin/tour) that contains answers to most common configuration and Drupal content management questions. This page:

• Organizes content into high-level concepts friendly to Drupal newbies. For example, Creating Content.
• Links to the appropriate documentation on docs.acquia.com, drupal.org, or Acquia Academy.
• Contains a dashboard that drives new Drupal admins to simplified config actions that are common for Drupal Starter Kits. For example, setting API keys or enabling key features. A Drupal novice should not need to have deep knowledge of Drupal configuration to get a Drupal Starter Kits site functional.

Start on the Tour page if you have basic questions about Drupal.

Why do I get out-of-memory issues during Composer install?

Composer uses a lot of memory when installing Drupal Starter Kits because it has multiple dependencies. To resolve this, you can do one of the following:

• Temporarily increase the memory at the command line. For example,

  php -d memory_limit=2G /usr/local/bin/composer install

• If you have access to the php.ini config file of your servers, you can increase the memory limit to memory_limit=2G or memory_limit=-1. It is a nuclear option that requires root access to the server, and also requires you to restart your webserver for the change to take effect. It is only reasonable for local environments and does not work in ACE/ACSF as you don’t have access. Therefore, Acquia recommends increasing the memory at the command line.

Why do I get out-of-memory issues during Drupal site install?

The Site Studio team is working to improve memory consumption. In the meantime, Drupal Starter Kits try to increase memory limits temporarily through code. If you are still experiencing out-of-memory errors, you can run the following command to install Drupal Starter Kits using Drush, as Drush is more efficient with memory than the user interface:

php -d memory_limit=2G vendor/bin/drush site:install acquia_cms --yes --account-pass admin

When working with the Site Studio API, installing and importing from Drush is more performant than using the Drupal admin UI. If you’re running into memory errors, try using Drush where you can override the memory limit.

Why do I get out-of-memory issues when enabling the Public Sector demo or Starter module?

This is the same issue as the one that you experience when installing the site. If you are enabling one of the Drupal Starter Kits modules that ships default content, you can run the following command:

php -d memory_limit=2G vendor/bin/drush pm:enable acquia_cms_demo_pubsec

How do I get started when my Drupal Starter Kits website is empty?

Enable one of the following modules:

• Drupal Starter Kits Public Sector Demo: It enables a complete website with a functional homepage, content detail pages, landing pages for all content types, built menus, and more. Note that this is for demonstration and training purposes only and is not meant to be a starting point for building an actual website with Drupal Starter Kits.
• Drupal Starter Kit Starter: It enables a small set of starter content and templates. This is meant to be a starting point for building an actual website. Note that it requires deleting some of the starter content because it is a filler.

After you get familiar with Drupal Starter Kits, you do not need either of the two demo content modules, and should be more comfortable starting from a blank canvas. However, you might still find some helpful things in Starter.

Why do I see errors about ‘the Google Maps API key is not set’ or ‘Unable to Geocode’?

Drupal Starter Kits collect a Google Maps API key on the Tour Dashboard at /admin/tour/ dashboard to keep things simple for the user. Drupal Starter Kits display Google Maps through the following features:

• In a Site Studio Map component that uses the API key stored at Admin > Site Studio > Configuration > Google Maps API Key.
• Displaying the Address field on a Place content type, which uses the API key stored at Admin > Configuration > System > Geocoders > Providers > Google.

If you observe one of the two errors, set the API key at Tour Dashboard and Drupal Starter Kits set the key at both places.

Why do I see duplicate menu content?

Duplicate menu items in the header indicate that the user installed both the Public Sector demo module and the Starter module. Both modules are not meant to be installed together. The admin UI shows an error to prevent the user from installing both modules. However, Drush does not show any error. To fix this, click Admin > Structure > Menus > menu-name and delete the duplicate content from the menu.

Why do I get the ‘Unable to send email. Contact the site administrator if the problem persists’ error when saving content?

This error occurs from the workflow notification module when you test in a local machine or Cloud IDE. Cloud IDEs and local dev environments, such as DevDesktop, DVM, and Lando, do not have a mail service installed at this time. You should test this feature in Drupal Starter Kits while hosted in Acquia Cloud. If you receive this error in Cloud Platform, proceed with troubleshooting the inability for Drupal to send email.

Why do I see Memcache errors in the browser, terminal, or logs?

Drupal Starter Kits come with built-in configuration for memcache that is disabled by default. Not all Drupal sites need memcache, and not all Drupal sites behave well with memcache. When memcache and Drupal misbehave, it’s almost always because of custom code or scaling issues with multisite. To make this easy to resolve without a code deploy, Drupal Starter Kits leverage a server-level toggle to enable or disable its integration with the memcached daemon.

• Acquia Cloud Enterprise - to enable memcache for ACE, you must set an environment variable. For more information, see Creating customer environment variables from the user interface.

  The variable is ENABLE_MEMCACHED and the value should be ‘1’. To disable, either set the value to ‘0’, or delete the variable.

• Site Factory - to enable memcache for ACSF, an Acquian needs to select the Enable Memcache checkbox for the applicable Site node. Disabling memcache is as simple as reversing the checkbox state. By default, ACSF has only one memcache server for each Factory, which all sites share. The default memory is fairly small. Therefore, a small number of sites in a Factory with memcache enabled will quickly cause memcache to overflow and cause more evictions than successful cache queries, which in turn will cause Drupal to slow down or go offline entirely. Acquia urges caution when implementing memcache for Drupal Starter Kits sites in ACSF.

When enabling or disabling Drupal Starter Kits integration with memcache, you might occasionally see a Drupal WSOD, which can be resolved by rebuilding the cache through Drush or admin UI. Therefore, Acquia does not recommend enabling or disabling memcache during high traffic.

Why are my pages empty after changing my Site Studio API key?

• Click Site Studio > Developer Tools > Rebuild to rebuild Site Studio assets.

  Alternatively, you can run the drush cohesion:rebuild command.

• Click Configuration > Search and Metadata > Search API, and click the currently-active index name.
• Click Rebuild Tracking Information.
• Click Index now.

When I try to use Site Studio page builder, why does it crash on existing pages but not on new pages?

You might experience page builder crashing if you enable Site Studio on your Drupal Starter Kits site with existing content, and use the page builder to edit the content.

The system displays the following error message:

cannot convert null or found to object

To resolve the error, upgrade to the current version of Site Studio.

Why do I get the ‘failed to drop or create the database’ or ‘Access denied for user’ warnings when installing Drupal Starter Kits locally?

Your settings file is either not set or misconfigured. Drupal will automatically copy default.settings.php to settings.php if it does not exist. Drupal Starter Kits add Acquia-specific settings configuration for the database to this file during the Composer install process. Drupal Starter Kits have no opinion or direct knowledge of any local development environments other than Cloud IDEs. For information about setting up the correct database settings, see the install documentation of your local dev environment of choice.

Why do I get Drupal Starter Kits version 1.2 and an ugly patch error when running ‘composer create-project acquia/drupal-recommended-project’ in a Cloud IDE?

There is an incompatibility between contenthub-console and Cloud IDEs that needs to be fixed. If you experience an issue on the acquia-cms-project repository, see Known issues in Drupal Starter Kits.

Why is the acquia_cms_minimal profile not present in Site Factory?

This issue occurs when the acquia_cms_minimal profile is removed from the codebase. Therefore, it is unavailable for installing the Drupal Starter Kits in Site Factory. For example, the following image does not display acquia_cms_minimal as an installation profile:

Workaround:

If you remove the acquia_cms_minimal profile from your codebase, you can add it again. To get the profile, contact Acquia Support.

Why are some of the patches not applied?

This issue occurs because of one of the following:

• Codebase mismatch: If a patch is created for a specific version of a module and your system uses a different version, there might be compatibility issues.
• Conflicting changes: If the patched code has undergone modifications, the changes introduced by the patch might conflict with these modifications.
• Incorrect patch version: Patches are version-specific. Therefore, any attempt to apply a patch designed for a different version of the modules might cause failures.

Workaround:

• Review patch documentation: Ensure that the patch you want to apply is compatible with your version of the module. You can refer to the patch’s documentation or the README file.
• Update to the latest module version: Update the Drupal Starter Kits module to the latest version. This might incorporate the changes included in the failed patch and therefore, negate the need for manual application. Ensure that you perform updates on a development or staging environment first to ensure compatibility.

By following these steps, you can apply patches to your Drupal Starter Kits module.

Why am I unable to update acquia_cms to the latest version?

This issue occurs when you explicitly require contributed modules that are already included with Drupal Starter Kits. This causes dependency deadlock and slows the upgrade process.

Workaround:

• Review dependencies: Review the dependencies listed in your project’s root composer.json file. Identify any modules that are provided by Drupal Starter Kits.
• Remove Drupal Starter Kits dependencies: Remove the direct dependencies associated with Drupal Starter Kits from the root composer.json file. This prevents conflicts during the upgrade process.

• Run Composer update: After you remove Drupal Starter Kits dependencies, run the following command:

  copy

  composer update acquia/acquia_cms -W

  The -W parameter ensures that your composer.lock file is updated with the latest compatible versions of the dependencies.

By following these steps, you can circumvent the dependency deadlock and enable a seamless update of Drupal Starter Kits to its latest version.

Here is an example of the composer.json file without direct dependencies:

Why am I unable to update certain contributed modules?

This issue occurs when you include a contributed module to a project while the Drupal Starter Kits distribution provides the same module. For example, this issue might occur when you update the Facets module to its latest version and add the module directly to the root composer.json file. However, this module is also a component in the Drupal Starter Kit Search module. Therefore, you can update the Facets module only by updating the Drupal Starter Kit Search module.

Workaround:

Remove any direct dependencies associated with the Drupal Starter Kits distribution from the root composer.json file. This establishes a clear path for the update process and eliminates any potential conflicts.