Updates to the troubleshooting docs, refs #10129
Jordi Boggiano
parent
44c5b6cde6
commit
8542321a31
|
|
@ -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`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue