Error: Dependency Resolution Failure¶
Note
bpt
implements the Pubgrub dependency resolution algorithm.
If you receive this error, it indicates that the requested dependencies create
one or more conflicts. bpt
will do its best to emit a useful explanation of
how this conflict was formed that can hopefully be used to find the original
basis for the conflict.
Every package can have some number of dependencies, which are other packages that are required for the dependent package to be used. Beyond just a package name, a dependency will also have a compatible version range.
Resolution Example¶
For example, let us suppose a package Widgets@4.2.8
may have a dependency
on Gadgets^2.4.4
and Gizmos^3.2.0
.
Note
The @4.2.8
suffix on Widgets
means that 4.2.8
is the exact
version of Widgets
, while the ^2.4.4
is a version range on
Gadgets
which starts at 2.4.4
and includes every version until (but
not including) 3.0.0
. ^3.2.0
is a version range on Gizmos
that
starts at 3.2.0
and includes every version until (but not including)
4.0.0
.
Now let us suppose the following versions of Gadgets
and Gizmos
are
available:
Gadgets
:2.4.0
2.4.3
2.4.4
2.5.0
2.6.0
3.1.0
Gizmos
:2.1.0
3.2.0
3.5.6
4.5.0
We can immediately rule out some candidates of Gadgets
: for the dependency
Gadgets^2.4.4
, 2.4.0
and 2.4.3
are too old, while 3.1.0
is
too new. This leaves us with 2.4.4
, 2.5.0
, and 2.6.0
.
We’ll first look at Gadgets@2.4.4
. We need to recursively solve its
dependencies. Suppose that it declares a dependency of Gizmos^2.1.0
. We
have already established that we require Gizmos^3.2.0
, and because
^2.1.0
and ^3.2.0
are disjoint (they share no common versions) we can
say that Gizmos^3.2.0
is incompatible with our existing partial solution,
and that its dependent, Gadgets@2.4.4
is transitively incompatible with
the partial solution. Thus, Gadgets@2.4.4
is out of the running.
This doesn’t mean we’re immediately broken, though. We still have two more
versions of Gadgets
to inspect. We’ll start with the next version in line:
Gadgets@2.5.0
. Suppose that it has a dependency on Gizmos^3.4.0
. We
have already established a requirement of Gizmos^3.2.0
, so we must find
a candidate for Gizmos
that satisfies both dependencies. Fortunately, we
have exactly one: Gizmos@3.5.6
satisfies both Gizmos^3.2.0
and
Gizmos^3.4.0
.
Suppose that Gizmos@3.5.6
has no further dependencies. At this point, we
have inspected all dependencies and have resolutions for every named package:
Thus, we have a valid solution of Widgets@4.2.8
, Gadgets@2.5.0
, and
Gizmos@2.6.0
! We didn’t even need to inspect Gadgets@2.6.0
.
In this case, bpt
will not produce an error, and the given package solution
will be used.
Breaking the Solution¶
Now suppose the same case, except that Gadgets@2.5.0
is not available.
We’ll instead move to check Gadgets@2.6.0
.
Suppose that Gadgets@2.6.0
has a dependency on Gizmos^4.0.6
. While we
do have a candidate thereof, we’ve already declared a requriement on
Gizmos^3.2.0
. Because ^4.0.6
and ^3.2.0
are disjoint, then there is
no possible satisfier for both ranges. This means that Gizmos^4.0.6
is
incompatible in the partial solution, and that Gadgets@2.6.0
is
transitively incompatible as well. It is no longer a candidate.
We’ve exhausted the available candidates for Gadgets^2.4.4
, so we must now
conclude that Gadgets^2.4.4
is also incompatible. Transitively, this also
means that Widgets@4.2.8
is incompatible as well.
We’ve reached a problem, though: Widgets@4.2.8
is our original requirement!
There is nothing left to invalidate in our partial solution, so we rule that
our original requirements are unsatisfiable.
At this point, bpt
will raise the error that dependency resolution has
failed. It will attempt its best to reconstruct the logic that we have used
above in order to explain what has gone wrong.
Fixing the Problem¶
There is no strict process for fixing these conflicts.
Fixing a dependency conflict is a manual process. It will require reviewing the available versions and underlying reasons that the dependency maintainers have chosen their compatibility ranges statements.
Your own dependency statements will often need to be changed, and sometimes even code will have to be revised to reach compatibility with newer or older dependency versions.