Troubleshooting

Start with:

jup info

This report does not contact the network. It shows invalid project fields instead of stopping at the first error, and it never prints credential values.

#A different package manager version runs

Check the Shims section of jup info.

If the jup shim directory is not on PATH, add the line printed by jup enable and open a new terminal. In an existing POSIX shell, run hash -r after changing PATH.

If another path appears before the jup shim, a system installation or another version manager is taking precedence. Move jup's shim directory earlier on PATH, or remove the conflicting command.

Remember that jup can select a version only when you use a jup shim or put jup before the package manager command.

#The project requires another package manager

In strict mode, jup rejects commands that conflict with the project declaration. A project pinned to pnpm will reject yarn install, for example.

Use the manager named in the error. If the mismatch is intentional for one command, disable strict mode for that invocation:

JUP_ENABLE_STRICT=0 jup yarn install

To change the project permanently, run:

jup use <name>@<version>

#jup found the wrong package.json

The error and jup info both show the manifest that supplied the pin. A packageManager field in $HOME/package.json, for example, can affect directories that have no closer declaration.

Remove an accidental field from the ancestor manifest. To create or update a pin only in the current directory, run:

jup use --here pnpm@11

#A range pin works locally but fails in CI

When CI is set, jup freezes .corepack.lock by default. Resolve the range locally:

jup up
git diff

Commit the updated .corepack.lock and any manifest change shown by the diff.

You can set JUP_FROZEN_LOCKFILE=0 to permit an update in CI, but a committed resolution is repeatable and does not require a registry lookup. If JUP_FROZEN_LOCKFILE=1 is explicitly set, even jup up will refuse to refresh the lockfile.

#The required version is missing from the cache

While online, cache the current project's package manager:

jup install

Or cache one exact release without changing the global fallback:

jup install -g --cache-only pnpm@11.1.2

For a machine with no registry access, create an archive with jup pack elsewhere and import it with jup install -g. See CI and offline use.

#A registry request fails

Run jup info and check the Package managers and .npmrc sections. Confirm the registry URL and the configuration file that supplied it.

Then check the relevant cause:

• Set JUP_NPM_REGISTRY to use an npm-compatible mirror for all managers.
• Set JUP_REGISTRY_NPM, JUP_REGISTRY_PNPM, or JUP_REGISTRY_YARN to move only one manager.
• Put credentials in your user .npmrc or process environment. jup refuses credentials from a project .npmrc.
• Set HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, or NO_PROXY if your network requires them.
• Increase JUP_NETWORK_TIMEOUT if the registry is reachable but slow.

jup includes the network or HTTP failure in its error and removes embedded credentials from displayed URLs.

#TLS certificate verification fails

If your company uses a TLS-inspecting proxy, obtain its CA certificate bundle and pass it to jup:

JUP_CAFILE=/path/to/company-ca.pem jup install

An expired certificate or hostname mismatch must be fixed by the registry or proxy owner.

JUP_STRICT_SSL=0 disables certificate verification and prints a warning on every run. Use it only to confirm a certificate problem, not as the permanent solution.

#Download verification fails

Do not bypass verification before checking why it failed.

#The digest does not match

The downloaded bytes differ from the project or lockfile pin. Confirm that the registry and mirror are the expected ones, inspect recent manifest or lockfile changes, and verify the artifact independently. Do not replace the pinned digest merely with the value shown by an unexpected source.

#The signing key is unknown

Allow network access so jup can fetch npm's current public keys, or update jup. If your organization uses its own registry keys, check JUP_INTEGRITY_KEYS and the registry origin it covers.

#The signing key has expired

Update the package source or use an exact digest obtained through a trusted process. jup does not accept expired keys automatically.

#The registry metadata has no signature

Some mirrors remove signatures. By default, jup can verify the registry digest and prints a warning. If JUP_REQUIRE_SIGNATURES=1 is set, use a registry that provides signed metadata or review whether that policy is required.

#There is no signature or digest

Pin a digest after independently reviewing the source. If bootstrapping requires unverified mode, limit it to that command:

JUP_ALLOW_UNVERIFIED=1 jup use yarn@4

Do not export JUP_ALLOW_UNVERIFIED globally. Commit the digest written by jup use so later runs can verify the download. Direct Yarn Berry downloads often require this first-use step; see Yarn Berry.

#jup enable cannot install a shim

jup refuses to overwrite a command from another installation by default. Review the path in the error. If you intend to replace it, run:

jup enable --force

jup disable restores an original command that jup recorded when it replaced that command. It does not restore unrelated changes made afterward.

For a read-only directory, choose a user-owned directory already on PATH:

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

#package.json is invalid

Fix the JSON syntax first. A declared "packageManager": null is invalid; it does not mean that the project has no pin. A malformed child manifest also stops the upward search so that jup does not silently use a parent declaration.

A minimal valid pin is:

{
  "packageManager": "pnpm@11.1.2"
}

Run jup use pnpm@11.1.2 to replace an old pin and add its digest.

#Collect details for a bug report

Create a machine-readable report:

jup info --json > jup-info.json

The report includes a top-level schema version and shows credentials only as set or unset. Attach it to a bug report together with the command you ran and the complete error output.