Troubleshooting Composer

Troubleshooting Composer can be frustrating. Composer is doing many complex things for you, and there's a degree of understanding required to effectively troubleshoot issues that arise.

This page is intended to provide troubleshooting techniques and to enumerate common problems. It is not intended to be exhaustive. If you're having a problem not described here, performing an internet search for your specific error message may be more helpful.

Troubleshooting techniques

Increase Composer's verbosity

E.g.,. when troubleshooting composer require drupal/module_name try adding a -vvv flag:

composer require drupal/module_name -vvv

Update Composer itself

Outdated versions of Composer can cause problems.

To update Composer itself to the latest version, just run the self-update command:

composer self-update

Common issues

Dependencies on projects removed from Drupal Core cause errors

Modules & themes are occasionally removed from Drupal Core, such as Forum. If a project in your codebase has a dependency on the removed component, it will resolve to the new project instead of Drupal Core, even if your site’s codebase still has an older version of Drupal that still has the component in core. For example:

  Problem 1
    - drupal/forum 1.0.0 requires drupal/core ^8 -> found drupal/core[8.0.0, ..., 8.9.20] but the package is fixed to 9.5.11 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
    - drupal/forum 1.0.1 requires drupal/core >=10.0 -> found drupal/core[10.0.0, ..., 10.2.5] but the package is fixed to 9.5.11 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
    - drupal/forum_access 1.0.0 requires drupal/forum * -> satisfiable by drupal/forum[1.0.0, 1.0.1].
    - Root composer.json requires drupal/forum_access ^1.0 -> satisfiable by drupal/forum_access[1.0.0].

Until your site has upgraded to a version of Drupal without the component, and added the new contributed project, you can tell Composer the dependency is provided. Add to your site’s composer.json:

    "provide": {
      "drupal/forum": "*"
    },

This can be removed as your site is upgraded to use the new contributed project.

Incompatibility with drush pm-updatecode

Some Drupal projects, such as Address, state something like "Address must be installed via Composer, in order to get the required libraries." While that is true, the user is not told that once one begins to use Composer to install modules and dependencies then any further use of Drush to update code via pm-updatecode will permanently hose up their entire Drupal site. Unfortunately, they will not find out that their site is hosed until the next time they run drush pm-updatecode. That will lead to highly charged discussions like this.

A faulty commit by a module developer can prevent any site from being updated

If you are using a module that has been installed by Composer and the maintainer of that module releases a faulty .json file, then it is possible that any site that has that module listed in its composer.lock file will get errors when composer require is ran. That is true because composer require will download the latest .json file every module that is listed in composer.lock. So if you have 50 modules being maintained by composer then a mistake introduced into any of the 50 modules will prevent your site from being updated, as has happened here. That is true even though the code you are trying to download via composer require has nothing to do with the faulty module.

Insufficient memory

Related errors include :

Fatal error: Allowed memory size
Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed -

The workaround for these errors is to run Composer with more, or even the maximum, memory that the system can provide. There are a variety of methods for accomplishing this. Some examples:

php -d memory_limit=-1 [composer-location] require drupal/module_name -vvv

Concrete Examples :
php -d memory_limit=-1 /usr/local/bin/composer require "drupal/address ~8.1" -vvv
php -d memory_limit=-1 /usr/local/bin/composer.phar require "drupal/address ~8.1" -vvv

Another straightforward solution to allowed memory size exhausted error is to use the COMPOSER_MEMORY_LIMIT environment variable, setting its value to -1. It can be added to the current Terminal session with:

$ export COMPOSER_MEMORY_LIMIT=-1

Once the COMPOSER_MEMORY_LIMIT variable is set, It will be used by all the composer commands you use in that session. Or,  it can be used on-demand by those Composer commands you know they need more than the memory_limit setting value you have set for your PHP installation with:

$ COMPOSER_MEMORY_LIMIT=-1 composer [command]

Composer hangs and eventually times out

Connection timeouts are often related to problems with IPv6, either on your computer or with your ISP. Verify this by turning IPv6 off.  This GitHub issue and these workarounds for Windows, Mac, and Linux may help too.

packagist.drupal-composer.org has been shut down

If you get the following error you are attempting to reach a discontinued composer repository:

[Composer\Downloader\TransportException]
The “https://packagist.drupal-composer.org/packages.json" file could not be downloaded: failed to open stream: Connection refused

If you are on Drupal 8, your composer.json file should be updated with code like this:

 { 
    "repositories": { 
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/8" 
        }
    }
}

More info here about this repository shutdown. The official documentation is here for setting up your project correctly.

Core update fails via composer update drupal/core

If you run composer update drupal/core and it fails with the message: 

Package "drupal/core" listed for update is not installed

Try opening composer.json and searching for a drupal/core entry in "replace"

   "replace": {
        "drupal/core": "~8.3"
    },

One solution is to move drupal/core from "replace" to "require", as below.

     "drupal/twitter_block": "^2.1",
     "drupal/core": "~8.3"
    },
    "replace": {},

The JSON file format requires a comma for all but not for the last item in each block. The empty replace section can be left or removed.

Composer is too slow when checking dependencies

There are some shortcomings to how Composer sequences its fetches. A plugin called prestissimo by hirak improves performance substantially by downloading packages in parallel. Installation is simple if you have access to global composer.

$ composer global require hirak/prestissimo

To uninstall:

$ composer global remove hirak/prestissimo