Troubleshooting

jup info

Use jup info --json when collecting machine-readable details. Credential values are masked, but review every attachment before sharing it.

#The wrong command runs

Check the Shims section, then ask the shell:

command -v pnpm
hash -r

In PowerShell:

Get-Command pnpm

Put jup's shim directory earlier on PATH, then open a new shell. Without a working shim, use jup pnpm ... explicitly.

A version manager such as nvm may prepend its own directory again at shell start. This is especially important after jup enable node: whichever node directory comes first wins.

#The project rejects another manager

A strict project configured for pnpm rejects ordinary Yarn or npm project commands. Use the declared manager or change the pin with jup use.

A one-command version override may change the version, not the manager:

jup pnpm@^12 --version

Set JUP_ENABLE_STRICT=0 only when intentionally using the other manager's global fallback. Transparent commands such as common dlx/x forms and global operations already bypass the project mismatch where appropriate.

bun, deno, nub, and node are never rejected this way. They are runtimes as well, so bun server.ts or deno run main.ts in a pnpm project runs the requested tool's own version instead of failing. The pin still applies in the other direction: in a project pinned to bun, another manager is rejected as usual.

#jup found the wrong project

jup info shows the selected manifest or version file. Read-only lookup walks upward, so a stray ancestor packageManager can affect many directories.

Write only the current manifest with:

jup use --here pnpm@^12

An invalid nearer manifest is an error rather than a reason to silently use a parent. A process-level JUP_SPEC_FILE replaces normal project pin fields and must point to an existing file.

#A shim will not install

jup leaves foreign entries alone by default. Inspect the path before replacing it:

command -v yarn
jup enable --force yarn

Use a writable directory already on PATH when the default cannot be used:

jup enable --install-directory "$HOME/bin"

Use the same directory option with disable. jup removes only entries it owns and will not restore a backup over a new foreign file.

If cache clean warns that shims depend on a cached Node interpreter, run jup enable under a durable Node.js outside the removable store to repin them.

#A range changes between machines

A range without a committed resolution can pick the newest locally available or registry-visible match. Record the decision:

jup use --lock pnpm@^12
git add package.json jup.lock

Refresh it deliberately with jup up. Add JUP_FROZEN_LOCKFILE=1 to jobs that must reject lockfile edits.

A registry tag remains movable. Resolve it to an exact pin with jup use pnpm@latest, or replace it with a range and commit jup.lock.

#Offline mode says a version is missing

List installed versions:

jup cache list

While connected, install the project tool or a named release:

jup cache install
jup cache install -g --cache-only pnpm@^12

For an air-gapped machine, import a trusted jup pack archive. Remember that jup's offline setting does not prepare or disable the package manager's own dependency network.

#Registry requests fail

Check registry and .npmrc sections in jup info.

• Confirm the selected mirror serves the expected package paths.
• Put auth in the process environment or user/global .npmrc.
• Check credential host/path scope.
• Configure HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY.
• Increase JUP_NETWORK_TIMEOUT for a slow but reachable server.
• A 401/403 usually needs credentials, not retries.
• A 404 for an exact version usually means the selected source does not have it.
• Check JUP_MINIMUM_RELEASE_AGE when no candidate qualifies.

An expired short-lived range memo is used only for temporary availability failures. It does not bypass auth, TLS, disabled networking, or policy errors.

#TLS fails

For a company proxy or private CA:

JUP_CAFILE=/path/to/company-roots.pem jup cache install

Use a complete PEM root bundle. Fix expired certificates and hostname mismatches at the server. JUP_STRICT_SSL=0 is a diagnostic exception, not a permanent fix.

#Download verification fails

#Digest mismatch

The downloaded bytes differ from the requested pin. Check manifest/lockfile diffs and the selected registry. Do not accept the reported digest until you verify the publisher's artifact independently.

#No trusted signing key

Allow jup to refresh npm's keys, update jup, or review your custom JUP_INTEGRITY_KEYS. A fixed custom trust store replaces built-in keys.

#No signature

jup can use a registry digest with a warning. If JUP_REQUIRE_SIGNATURES=1, use a signed source or a trusted project digest.

#No usable check at all

After independent verification, a one-command bootstrap is available:

JUP_ALLOW_UNVERIFIED=1 jup use <tool>@<version>

Review the written pin and confirm the next run succeeds without the override.

#A project env setting is ignored

Project env files accept only the entries marked “Yes” in Settings. Move credentials, store/shim paths, CA/trust settings, unsafe URL permission, spec-file overrides, and verification opt-outs to the real user or CI environment.

The nearest .jup.env wins. .corepack.env is tried only when .jup.env is absent in that same directory. Set process JUP_ENV_FILE=0 to disable project env files.

#Node.js cannot run

The jup npm package needs the Node.js version declared by its package metadata. The install scripts can bootstrap a supported runtime on supported hosts. On musl Linux, install Node.js through the system or another trusted source first.

A Node version selected by jup is separate from the runtime that starts jup. Without a working host runtime, jup cannot start far enough to select another one.

#package.json is invalid

Fix JSON syntax and the declaration itself. Minimal valid examples:

{ "packageManager": "pnpm@12.0.0" }

{
  "devEngines": {
    "runtime": { "name": "node", "version": "^22" }
  }
}

Use jup use to write a checked exact pin or a recorded range instead of hand editing integrity values.

#Report a bug

Collect:

jup --version
jup info --json > jup-info.json

Include the operating system, architecture, exact command, exit code, and relevant stdout/stderr. Remove secrets, private URLs, user paths, and project data before sharing. A proxied tool's own logs are not sanitized by jup.