-
Notifications
You must be signed in to change notification settings - Fork 180
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1041 from pauby/doc/add-dependency-yt-video
(doc) Add dependency issues YouTube video
- Loading branch information
Showing
1 changed file
with
97 additions
and
93 deletions.
There are no files selected for viewing
190 changes: 97 additions & 93 deletions
190
src/content/docs/en-us/choco/troubleshooting/dependency-troubles.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,93 +1,97 @@ | ||
| --- | ||
| order: 10 | ||
| xref: choco-dependency-troubles | ||
| title: Dependency Troubleshooting in Chocolatey CLI | ||
| description: Troubleshooting steps for when you encounter issues related to dependencies | ||
| --- | ||
| import Callout from '@choco/components/Callout.astro'; | ||
| import Iframe from '@choco/components/Iframe.astro'; | ||
| import Xref from '@components/Xref.astro'; | ||
|
|
||
| ## Installation and Upgrade Commands Fail for Many Seemingly Unrelated Packages | ||
|
|
||
| Due to the way dependency resolution works, packages with dependencies can occasionally trigger undesirable behavior. | ||
| When this happens, you will often be presented with both warnings and errors. | ||
| The most important information will be in the errors, and not the warnings. | ||
|
|
||
| When you encounter these errors, it is recommended to start with the package name mentioned in the error, and attempt to install it. | ||
| Repeat this process with any other failing dependencies until they're all installed. | ||
|
|
||
| ### Example 1 - Upgrade All Fails to Upgrade One or More Packages | ||
|
|
||
| This will sometimes be encountered with meta-packages, such as `obs-studio` which takes an exact-version dependency on `obs-studio.install`. | ||
| When running `choco upgrade all` it will attempt to upgrade every installed package. | ||
| Any packages which fail to install may be retried as part of a later dependency chain. | ||
| For example, `obs-studio.install` may be upgraded, fail, and then later be tried again as part of the dependency chain for `obs-studio` itself. | ||
| As a result, Chocolatey CLI's packages may be in an inconsistent state. | ||
| This is typically characterized by a dependency resolution error message when performing package operations: | ||
|
|
||
| ``` | ||
| Unable to resolve dependencies. 'obs-studio.install 29.0.2' is not compatible with 'obs-studio 29.1.1 constraint: obs-studio.install (>= 29.1.1)'. | ||
| ``` | ||
|
|
||
| This is normally resolved by upgrading the affected dependency. | ||
| In this example, you would run `choco upgrade obs-studio.install` to resolve the issue. | ||
|
|
||
| The following scenario illustrates what can happen during an `upgrade all` where a dependency fails to install. | ||
| In this example, `obs-studio` installs, but `obs-studio.install` fails. | ||
| Due to the dependency version range specified by `obs-studio`, the version of `obs-studio.install` that remains installed (due to the upgrade failure) does not satisfy the dependency requirement. | ||
|
|
||
| To resolve the issue, we run `choco upgrade obs-studio.install` to get the correct dependency version installed. | ||
| For packages that have a specific version dependency, add the `--version` option and specify the exact version to install. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Example 2 - Installing a Package Fails Due to Existing Missing Dependencies | ||
|
|
||
| <Callout type="warning"> | ||
| This example deals with multiple missing dependencies, and installs them while ignoring dependencies. | ||
| You will need to ensure you're installing the correct versions required for your dependencies. | ||
| </Callout> | ||
|
|
||
| The following scenario illustrates what can happen during an `install` where multiple existing packages have dependencies that are not currently met. | ||
| In this example, `glab` is attempting to be installed, but a number of `KB` packages are missing from the Chocolatey `lib` directory. | ||
|
|
||
| 1. We start by attempting to install `glab`, and note that that the following error occurs. | ||
|
|
||
|  | ||
|
|
||
| 1. To resolve the issue, we first run `choco install KB3063858` to install the first identified package. | ||
| We note that this fails to install, so we make note of the package it couldn't find (`KB2919355`) and we run `choco install KB3063858 --ignore-dependencies` to ignore the dependency failure. | ||
|
|
||
|  | ||
|
|
||
| 1. Now that we have `KB3063858` installed, we attempt to run `choco install KB2919355` to install the next identified package. | ||
| Again we make note of the next package (`KB2999226`) and install this package while ignoring dependencies: `choco install KB2919355 --ignore-dependencies`. | ||
|
|
||
|  | ||
|
|
||
| 1. Now with `KB2919355` installed we continue with `choco install KB2999226`. | ||
| Again we make note of the next package (`KB2919442`) and install this package while ignoring dependencies: `choco install KB2999226 --ignore-dependencies`. | ||
|
|
||
|  | ||
|
|
||
| 1. Now with `KB2999226` installed, we attempt to run `choco install KB2919442`. | ||
| We see that this one is actually already installed, so we attempt to install `glab` again. | ||
| When `glab` fails to install, we make note of the next package missing in our chain: `chocolatey-windowsupdate.extension`. | ||
|
|
||
|  | ||
|
|
||
| 1. We install this in the same way as before (`choco install chocolatey-windowsupdate.extension`, then `choco install chocolatey-windowsupdate.extension --ignore-dependencies`). | ||
|
|
||
|  | ||
|
|
||
| 1. We install the next package (`KB3033929`) and note that it did not have any dependency failures. | ||
|
|
||
|  | ||
|
|
||
| 1. So, we attempt our install of `glab` once more. | ||
| Thankfully, we are able to install it with no dependency errors. | ||
|
|
||
|  | ||
| --- | ||
| order: 10 | ||
| xref: choco-dependency-troubles | ||
| title: Dependency Troubleshooting in Chocolatey CLI | ||
| description: Troubleshooting steps for when you encounter issues related to dependencies | ||
| --- | ||
| import Callout from '@choco/components/Callout.astro'; | ||
| import Iframe from '@choco/components/Iframe.astro'; | ||
| import Xref from '@components/Xref.astro'; | ||
|
|
||
| ## Installation and Upgrade Commands Fail for Many Seemingly Unrelated Packages | ||
|
|
||
| Due to the way dependency resolution works, packages with dependencies can occasionally trigger undesirable behavior. | ||
| When this happens, you will often be presented with both warnings and errors. | ||
| The most important information will be in the errors, and not the warnings. | ||
|
|
||
| When you encounter these errors, it is recommended to start with the package name mentioned in the error, and attempt to install it. | ||
| Repeat this process with any other failing dependencies until they're all installed. | ||
|
|
||
| In a previous livestream we demoed some of the dependency issues you may experience. | ||
|
|
||
| <Iframe ratio="16x9" link="https://www.youtube.com/embed/mulMztVQzQU?si=ZOFdN8Tr4cjB0Dt6&start=1208" title="Troubleshooting Chocolatey Package Dependencies" /> | ||
|
|
||
| ### Example 1 - Upgrade All Fails to Upgrade One or More Packages | ||
|
|
||
| This will sometimes be encountered with meta-packages, such as `obs-studio` which takes an exact-version dependency on `obs-studio.install`. | ||
| When running `choco upgrade all` it will attempt to upgrade every installed package. | ||
| Any packages which fail to install may be retried as part of a later dependency chain. | ||
| For example, `obs-studio.install` may be upgraded, fail, and then later be tried again as part of the dependency chain for `obs-studio` itself. | ||
| As a result, Chocolatey CLI's packages may be in an inconsistent state. | ||
| This is typically characterized by a dependency resolution error message when performing package operations: | ||
|
|
||
| ``` | ||
| Unable to resolve dependencies. 'obs-studio.install 29.0.2' is not compatible with 'obs-studio 29.1.1 constraint: obs-studio.install (>= 29.1.1)'. | ||
| ``` | ||
|
|
||
| This is normally resolved by upgrading the affected dependency. | ||
| In this example, you would run `choco upgrade obs-studio.install` to resolve the issue. | ||
|
|
||
| The following scenario illustrates what can happen during an `upgrade all` where a dependency fails to install. | ||
| In this example, `obs-studio` installs, but `obs-studio.install` fails. | ||
| Due to the dependency version range specified by `obs-studio`, the version of `obs-studio.install` that remains installed (due to the upgrade failure) does not satisfy the dependency requirement. | ||
|
|
||
| To resolve the issue, we run `choco upgrade obs-studio.install` to get the correct dependency version installed. | ||
| For packages that have a specific version dependency, add the `--version` option and specify the exact version to install. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Example 2 - Installing a Package Fails Due to Existing Missing Dependencies | ||
|
|
||
| <Callout type="warning"> | ||
| This example deals with multiple missing dependencies, and installs them while ignoring dependencies. | ||
| You will need to ensure you're installing the correct versions required for your dependencies. | ||
| </Callout> | ||
|
|
||
| The following scenario illustrates what can happen during an `install` where multiple existing packages have dependencies that are not currently met. | ||
| In this example, `glab` is attempting to be installed, but a number of `KB` packages are missing from the Chocolatey `lib` directory. | ||
|
|
||
| 1. We start by attempting to install `glab`, and note that that the following error occurs. | ||
|
|
||
|  | ||
|
|
||
| 1. To resolve the issue, we first run `choco install KB3063858` to install the first identified package. | ||
| We note that this fails to install, so we make note of the package it couldn't find (`KB2919355`) and we run `choco install KB3063858 --ignore-dependencies` to ignore the dependency failure. | ||
|
|
||
|  | ||
|
|
||
| 1. Now that we have `KB3063858` installed, we attempt to run `choco install KB2919355` to install the next identified package. | ||
| Again we make note of the next package (`KB2999226`) and install this package while ignoring dependencies: `choco install KB2919355 --ignore-dependencies`. | ||
|
|
||
|  | ||
|
|
||
| 1. Now with `KB2919355` installed we continue with `choco install KB2999226`. | ||
| Again we make note of the next package (`KB2919442`) and install this package while ignoring dependencies: `choco install KB2999226 --ignore-dependencies`. | ||
|
|
||
|  | ||
|
|
||
| 1. Now with `KB2999226` installed, we attempt to run `choco install KB2919442`. | ||
| We see that this one is actually already installed, so we attempt to install `glab` again. | ||
| When `glab` fails to install, we make note of the next package missing in our chain: `chocolatey-windowsupdate.extension`. | ||
|
|
||
|  | ||
|
|
||
| 1. We install this in the same way as before (`choco install chocolatey-windowsupdate.extension`, then `choco install chocolatey-windowsupdate.extension --ignore-dependencies`). | ||
|
|
||
|  | ||
|
|
||
| 1. We install the next package (`KB3033929`) and note that it did not have any dependency failures. | ||
|
|
||
|  | ||
|
|
||
| 1. So, we attempt our install of `glab` once more. | ||
| Thankfully, we are able to install it with no dependency errors. | ||
|
|
||
|  |