# Troubleshooting

Start with:

```sh
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:

```sh
JUP_ENABLE_STRICT=0 jup yarn install
```

To change the project permanently, run:

```sh
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:

```sh
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:

```sh
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:

```sh
jup install
```

Or cache one exact release without changing the global fallback:

```sh
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](./ci-and-offline).

## 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:

```sh
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:

```sh
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](./security#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:

```sh
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`:

```sh
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:

```json
{
  "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:

```sh
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.