Rez resolve and solver

One-sentence summary: the solver narrows scopes of candidate variants until each contains exactly one variant; if it cannot, it reports the failure reason — a conflict, a cycle, or a total reduction.

Skill scope: how the solver works and how to read its output. For request/version syntax see rez-core-concepts; for the CLI surface see rez-cli. For a failing resolve you need to attribute, see rez-resolve-troubleshooting.

The algorithm

State model:

• A phase is one state of the solve; it holds a list of scopes.
• A scope is one package request plus the list of variants matching it.

Five operations drive a phase (EXTRACT, MERGE-EXTRACTIONS, INTERSECT, ADD, REDUCE). A sixth, SPLIT, is the cross-phase operation that runs when a phase can go no further:

The solver keeps a phase stack (not recursion): pop a phase, solve it; if exhausted, split and push two; if solved, done; if failed, pop — empty stack means no solution.

Two implementation notes that explain its behavior and speed:

• Scopes cache a set of package families to skip unnecessary reductions — reducing a foo scope that only touches python/bah against maya is effectively a no-op.
• Solver objects are immutable; each change creates a new object built on a shallow copy. That is copy-on-demand, so phases on the stack share state cheaply.

Reading -v debug output

Enable with rez-env -v, up to -vvv.

Scope syntax

Output sections in order

request: foo-1.2 bah-3 ~foo-1            # initial request, printed once
merged request: foo-1.2 bah-3            # simplified; ~foo-1 absorbed by foo-1.2
pushed {0,0}: [foo==1.2.0[0,1]]* bah[...] # phase pushed: {stack depth, phases solved at depth}
--------------------------------------------------------------------------------
SOLVE #1...
--------------------------------------------------------------------------------
popped {0,0}: ...
EXTRACTING:
extracted python-2 from [foo==1.2.0[0,1]]*
MERGE-EXTRACTIONS:
merged extractions are: python-2 utils-1.2+
INTERSECTING:
python[2.7.3..3.3.0(3)] was intersected to [python==2.7.3] by range '2'
ADDING:
added utils[1.2.0..5.2.0(12:14)]*
  REDUCING:
  removed blah-35.0.2[1] (dep(python-3.6) <--!--> python==2.7.3)
  [blah==35.0.2[0,1]] was reduced to [blah==35.0.2[0]]* by python==2.7.3

<--!--> marks a conflict between two requirements.

Failure modes

Typical output:

The context failed to resolve:
The following package conflicts occurred: (.foo-1 <--!--> .foo-2)

Triage workflow

Work cheapest-first; do not jump to -vvv.

1. Reproduce without entering a shell

   rez-env <reqs> --output context.rxt     # or -o
   

2. Ask rez what it thinks

   rez-env <reqs> -v          # solver steps
   rez-context --so           # source order of the last resolve
   rez-status                 # environment/repo sanity
   

3. Inspect the failure graph — usually the fastest way to see who introduced a requirement

   rez-env <reqs> --fail-graph                 # render on failure
   rez-context --dependency-graph              # dot graph of the resolve
   rez-context --print-graph                   # compact text graph
   rez-env <reqs> --max-fails N                # collect more than the first failure
   

4. Find the real requirer — the package you asked for is rarely the one causing it

   rez-depends <pkg>          # reverse lookup: who depends on <pkg>
   rez-search <pkg>           # what versions exist
   

5. Narrow the request — bisect: drop requests until it resolves, then add back.
6. Only then go to -vvv.

Common causes and fixes

Patching

When a dependency is wrong but you cannot edit it yet, patch at resolve time:

rez-env <reqs> --patch
rez-env <reqs> --patch --patch-rank 3      # apply additional patches

Caching

Two independent caches, both easy to blame wrongly:

• Resolve caching (resolve_caching, default True) — cached resolves can be returned with a stale timestamp. Bypass with rez-env --no-cache.
• Package caching (default_cachable, default False) — package payloads copied to cache_packages_path. When retargeted, REZ_<PKG>_ROOT changes but REZ_<PKG>_ORIG_ROOT keeps the original.

Memcached (memcached_uri) can back both. If a resolve returns something impossible, retry with --no-cache before investigating the solver.

Timestamps

Resolves carry a timestamp, so a resolve is reproducible later.

To pin a resolve to a point in time, pass rez-env -t/--time (epoch time such as 1393014494, or a relative time such as -10s, -5m, -0.5h, -10d). That is the input that controls the solve — it ignores packages released after the given time.

REZ_USED_TIMESTAMP and REZ_USED_REQUESTED_TIMESTAMP are outputs only — Rez sets them in the resolved environment, and nothing reads them back to influence a later solve. Exporting them by hand will not reproduce a historical resolve; use -t/--time for that.

warn_untimestamped / warn_all surface packages that resolved without one.

Useful knobs

Agent workflow

1. Reproduce with -o context.rxt; never debug inside an interactive subshell.
2. Read --fail-graph / --print-graph before reading verbose logs — the graph is smaller and answers "who required this" directly.
3. Use rez-depends for reverse lookups rather than grepping every package.py.
4. Bisect the request; keep the failure minimal.
5. Confirm the fix with a fresh resolve, and re-check with --no-cache if anything looked stale.