Troubleshooting Composer Errors
Why Composer? #
Like any modern PHP application, Craft CMS manages dependencies with Composer. (If you’ve used npm, it’s a similar idea for PHP.)
If you’re new to package managers in general, Composer may first seem like a cumbersome and frustrating tool because of its tendency to get stuck on incompatibilities and errors. This is actually Composer’s primary benefit; it exposes software conflicts before updates are applied, rescuing clients, customers, and visitors from errors that never had a chance to happen in production.
What Composer Does #
Composer looks for a valid composer.json file that describes the PHP packages you intend to use in your project—that’s what the all-important require section is for, while require-dev describes a subset of items meant strictly for development and testing rather than production use.
These packages will be installed in your project’s vendor/ directory, and you’ll see more items there than you specified in your composer.json file because each of your required packages may also require dependencies of its own. Managing all these packages and requirements safely is exactly the problem Composer is designed to solve.
When you run composer update, composer traverses the complex web of dependencies to update packages according to your constraints and those of every other dependency in the tree. If there are no conflicts, the relevant files in vendor/ are updated and composer.lock is written to record precisely what was downloaded and at what version.
Run composer show --tree to inspect the entire dependency map.
You can commit composer.lock and run composer install in production to pull down those already-safe updated dependencies in far less time than composer update would require. (More on that in Deployment Best Practices.)
While you don’t need to be a Composer expert to work with it, it’s important to understand how the subtle differences in version constraints can be important, as well as the implications for a project’s minimum-stability designation.
Update vs. Install #
Generally speaking, it’s best to run composer update in development where you can test and confirm that your updated packages behave as expected, committing composer.lock once you’re confident that set of packages is ready for other environments.
Unless there were errors running composer update, it will then be safe to pull that new composer.lock file into another environment and run composer install to read it and bring that environment’s vendor/ folder up to date.
Both composer.json and composer.lock should be committed and deployed across environments.
Permissions Issues #
Systems may use different permissions setups, but Composer should always be run by whatever user normally executes PHP. If you’re seeing permissions issues, that is most likely the problem to solve.
Running Composer as a super user (i.e. with sudo) may force a certain action to succeed where it had previously failed, but you’ll want to be sure the resulting vendor/ directory has appropriate permissions so it doesn’t lead to further problems.
composer diagnose #
Running the composer diagnose terminal command gives you a quick sanity check. Consider using it to rule out more basic system-level problems:
$ composer diagnose
Checking platform settings: OK
Checking git settings: OK
Checking http connectivity to packagist: OK
Checking https connectivity to packagist: OK
Checking github.com oauth access: OK
Checking disk free space: OK
Checking pubkeys:
Tags Public Key Fingerprint: 57815BA2 7E54DC31 7ECC7CC5 573090D0 87719BA6 8F3BB723 4E5D42D0 84A14642
Dev Public Key Fingerprint: 4AC45767 E5EC2265 2F0C1167 CBBB8A2B 0C708369 153E328C AD90147D AFE50952
OK
Checking composer version: OK
Composer version: 2.0.6
PHP version: 7.4.12
PHP binary path: /usr/local/Cellar/php/7.4.12/bin/php
OpenSSL version: OpenSSL 1.1.1h 22 Sep 2020
cURL version: 7.73.0 libz 1.2.11 ssl OpenSSL/1.1.1h
zip extension: OK
Common Composer Errors #
“Your requirements could not be resolved to an installable set of packages.” #
This is the most common message you’ll see with an update failure, and it will always be preceded by details that describe one or more dependency conflicts.
“No such file or directory in /autoload.php” #
Composer generates and updates a file named autoload.php an app like Craft can include once to load all its dependencies. Sometimes missing file errors mentioning autoload.php or autoload_real.php indicate an altered or corrupt vendor folder. In this case, it’s usually simplest to delete the vendor folder and reinstall all the dependencies:
rm -rf vendor/
composer install
“yiisoft/yii2-composer contains a Composer plugin which is currently not in your allow-plugins config.” #
Composer 2.2+ will show this error unless you add the following to your composer.json file’s config section:
"allow-plugins": {
"craftcms/plugin-installer": true,
"yiisoft/yii2-composer": true
},
This is included by default in new Craft CMS projects.