From 8542321a31a129398eebb87f819b33c15615fc60 Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Thu, 11 Nov 2021 14:58:43 +0100 Subject: [PATCH] Updates to the troubleshooting docs, refs #10129 --- doc/articles/troubleshooting.md | 40 ++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/doc/articles/troubleshooting.md b/doc/articles/troubleshooting.md index 0182f9231..85419c61e 100644 --- a/doc/articles/troubleshooting.md +++ b/doc/articles/troubleshooting.md @@ -5,6 +5,7 @@ This is a list of common pitfalls on using Composer, and how to avoid them. + ## General 1. When facing any kind of problems using Composer, be sure to **work with the @@ -23,6 +24,7 @@ This is a list of common pitfalls on using Composer, and how to avoid them. possible interferences with existing vendor installations or `composer.lock` entries. + ## Package not found 1. Double-check you **don't have typos** in your `composer.json` or repository @@ -47,6 +49,12 @@ This is a list of common pitfalls on using Composer, and how to avoid them. In this case add the `--with-dependencies` argument **or** add all dependencies which need an update to the command. + +## Package is not updating to the expected version + +Try running `php composer.phar why-not [package-name] [expected-version]`. + + ## Dependencies on the root package When your root package depends on a package which ends up depending (directly or @@ -69,6 +77,7 @@ indirectly) back on the root package itself, issues can occur in two cases: the variable only for the call to composer, or you can define it globally in the CI env vars. + ## Package not found in a Jenkins-build 1. Check the ["Package not found"](#package-not-found) item above. @@ -81,6 +90,7 @@ indirectly) back on the root package itself, issues can occur in two cases: branch as you are checking out. Using this, the checkout will not be in detached state any more and the dependency on the root package should become satisfied. + ## I have a dependency which contains a "repositories" definition in its composer.json, but it seems to be ignored. The [`repositories`](../04-schema.md#repositories) configuration property is defined as [root-only](../04-schema.md#root-package). It is not inherited. You can read more about the reasons behind this in the "[why can't @@ -88,6 +98,7 @@ Composer load repositories recursively?](../faqs/why-can't-composer-load-reposit The simplest work-around to this limitation, is moving or duplicating the `repositories` definition into your root composer.json. + ## I have locked a dependency to a specific commit but get unexpected results. While Composer supports locking dependencies to a specific commit using the `#commit-ref` syntax, there are certain @@ -103,6 +114,7 @@ frequently overlooked: There is no simple work-around to this limitation. It is therefore strongly recommended that you do not use it. + ## Need to override a package version Let's say your project depends on package A, which in turn depends on a specific @@ -123,8 +135,18 @@ composer.json: See [aliases](aliases.md) for more information. + +## Figuring out where a config value came from + +Use `php composer.phar config --list --source` to see where each config value originated from. + + ## Memory limit errors +The first thing to do is to make sure you are running Composer 2, and if possible 2.2.0 or above. + +Composer 1 used much more memory and upgrading to the latest version will give you much better and faster results. + Composer may sometimes fail on some commands with this message: `PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...>` @@ -161,6 +183,7 @@ php -d memory_limit=-1 composer.phar <...> This issue can also happen on cPanel instances, when the shell fork bomb protection is activated. For more information, see the [documentation](https://documentation.cpanel.net/display/68Docs/Shell+Fork+Bomb+Protection) of the fork bomb feature on the cPanel site. + ## Xdebug impact on Composer To improve performance when the Xdebug extension is enabled, Composer automatically restarts PHP without it. @@ -170,6 +193,7 @@ Composer will always show a warning if Xdebug is being used, but you can overrid `COMPOSER_DISABLE_XDEBUG_WARN=1`. If you see this warning unexpectedly, then the restart process has failed: please report this [issue](https://github.com/composer/composer/issues). + ## "The system cannot find the path specified" (Windows) 1. Open regedit. @@ -178,6 +202,7 @@ please report this [issue](https://github.com/composer/composer/issues). or `HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Command Processor`. 3. Check if it contains any path to non-existent file, if it's the case, remove them. + ## API rate limit and OAuth tokens Because of GitHub's rate limits on their API it can happen that Composer prompts @@ -188,7 +213,9 @@ manually create a token using the [procedure documented here](authentication-for Now Composer should install/update without asking for authentication. + ## proc_open(): fork failed errors + If Composer shows proc_open() fork failed on some commands: `PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar` @@ -214,6 +241,7 @@ To enable the swap you can use for example: ``` You can make a permanent swap file following this [tutorial](https://www.digitalocean.com/community/tutorials/how-to-add-swap-on-ubuntu-14-04). + ## proc_open(): failed to open stream errors (Windows) If Composer shows proc_open(NUL) errors on Windows: @@ -227,6 +255,7 @@ service. The issue was fixed in PHP 7.2.23 and 7.3.10. Alternatively it could be because the Windows Null Service is not enabled. For more information, see this [issue](https://github.com/composer/composer/issues/7186#issuecomment-373134916). + ## Degraded Mode Due to some intermittent issues on Travis and other systems, we introduced a @@ -246,9 +275,9 @@ If you have been pointed to this page, you want to check a few things: routing rules between you and Packagist (i.e. the internet at large). The best way to get these fixed is raise awareness to the network engineers that have the power to fix it. Take a look at the next section for IPv6 workarounds. - - If none of the above helped, please report the error. + ## Operation timed out (IPv6 issues) You may run into errors if IPv6 is not configured correctly. A common error is: @@ -300,6 +329,7 @@ That said, if this fixes your problem, please talk to your ISP about it to try and resolve the routing errors. That's the best way to get things resolved for everyone. + ## Composer hangs with SSH ControlMaster When you try to install packages from a Git repository and you use the `ControlMaster` @@ -317,9 +347,9 @@ php composer.phar update See also https://github.com/composer/composer/issues/4180 for more information. + ## Zip archives are not unpacked correctly. -Composer can unpack zipballs using either a system-provided `unzip` utility or PHP's -native `ZipArchive` class. The `ZipArchive` class is preferred on Windows. On other -OSes where ZIP files can contain permissions and symlinks, the `unzip` utility is -preferred. You're advised to install it if you need these features. +Composer can unpack zipballs using either a system-provided `unzip` or `7z` (7-Zip) utility, or PHP's +native `ZipArchive` class. On OSes where ZIP files can contain permissions and symlinks, we recommend +installing `unzip` or `7z` as these features are not supported by `ZipArchive`.