Troubleshooting

Start with jrt doctor. It checks everything jrt depends on and tells you the exact command to fix each problem.

jrt doctor

shell

jrt doctor          # report problems
jrt doctor --fix    # repair everything that is safe to repair

It checks:

the managed mise backend
the tool registry and compatibility overrides
shim health (missing or stale shims)
signed compatibility layers that have expired
leftovers from interrupted runs: abandoned locks, partial .tmp writes, half-finished downloads, retired shims

--fix removes only what is safe to delete. Locks held by a running jrt process are never removed.

Crash safety

Registry and rule updates are serialized with lock files and written atomically, so parallel jrt tool add calls cannot lose each other’s changes. Each lock records its owner’s PID: a lock left by a crashed process is recovered automatically, while one held by a live process — even a long Cargo build — is respected. A tool is only trusted once its install finished completely, so an interrupted install is simply redone.

Common problems

Symptom	Fix
`mise is not installed; run jrt backend bootstrap`	Run `jrt backend bootstrap` once.
`node` still runs the system version inside a project	Shims are not first on `PATH`, or the project has no `.jrt.toml`. Check `jrt shim path` and `jrt current`.
Shims report stale after upgrading jrt	`jrt shim sync`
A tool picked an unexpected runtime	`jrt why <alias>` shows the policy and reason. Adjust with `jrt compat set`, `jrt tool pin` or `jrt tool policy`.
A Cargo crate refuses to register	It has no MSRV metadata. Add `--runtime rust@…` or a `jrt compat set cargo:<crate>` rule.
A package manager is refused	It does not match `package.json#packageManager`. Use the pinned one or update the field.
Slow or unreliable network	Downloads only fail after 60 seconds without receiving data, so slow links finish. Just retry after a real outage.

Disk space

shell

jrt storage          # disk usage per cache and install area
jrt cache clean      # drop disposable caches, keep shared downloads
jrt cache clean --all

cache clean keeps the shared download caches (npm, PyPI, Go modules, Cargo, NuGet, Maven, Bun, Deno, RubyGems) so reinstalls stay fast; --all removes those too. Already-installed tools keep working either way.

Still stuck?

Report it with the output of jrt doctor and jrt why <alias> — together they say which runtime was picked and why.