Troubleshooting

A first-aid kit for the most common problems. When something is off, the fastest signal is usually snpm config plus snpm --verbose <cmd>.

Diagnostics

snpm config              # resolved paths, registry, install settings, allow-scripts
snpm --verbose install   # full install trace (also written to .snpm.log when verbose)
snpm store status        # store size and counts
snpm why <pkg>           # explain why a transitive package is installed

Installation issues

snpm: command not found

If you installed via npm: make sure the npm global bin directory is on PATH. Try:

npm bin -g
export PATH="$(npm bin -g):$PATH"

If you installed via cargo install, add the cargo bin directory:

export PATH="$HOME/.cargo/bin:$PATH"

cargo install --path snpm-cli fails

Update the Rust toolchain:

rustup update stable

Then rebuild from a clean target dir:

cargo clean
cargo install --path snpm-cli --force

Pinned packageManager version not found

snpm-switch downloads the requested version on demand. If you're offline or the version isn't reachable, override the pin for this command:

snpm --switch-ignore-package-manager install

Or run with a known good version:

snpm --switch-version 2026.5.16 install

Install issues

--frozen-lockfile fails

The lockfile is missing or out of sync with package.json. Locally:

snpm install
git add snpm-lock.yaml
git commit -m "Refresh lockfile"

If you only want to re-resolve drifted entries:

snpm install --fix-lockfile

Install scripts were blocked

snpm prints which packages had their scripts blocked. Add the trusted ones to the allow-list:

export SNPM_ALLOW_SCRIPTS="esbuild,sharp"
snpm install
snpm rebuild   # apply policy to already-extracted packages

Or, more durable, set it in the workspace file:

onlyBuiltDependencies:
  - esbuild
  - sharp

"package not found" / 404

• Check the package name and version: snpm dlx npm view <name>.
• For private registries, confirm auth is set: snpm config should show default auth: bearer (set) (or basic (set)).
• For scoped registries, make sure both @scope:registry=... and //host/:_authToken=... are configured.

Slow installs

• Increase concurrency on fast networks: export SNPM_REGISTRY_CONCURRENCY=256.
• Make sure the store is on a fast disk (snpm store path).
• In CI, cache the store directory between runs (see CI/CD).
• Re-check the lockfile mode — --frozen-lockfile skips network resolution entirely when the lockfile is valid.

Recently published packages are skipped

SNPM_MIN_PACKAGE_AGE_DAYS is filtering them out. Confirm with:

snpm config | grep "min package age"

Lower the threshold or unset the variable for the current shell.

Workspace issues

Workspace not detected

snpm walks up the directory tree looking for one of these, in order:

1. snpm-workspace.yaml
2. pnpm-workspace.yaml
3. package.json with a workspaces field

If none of those are present in the current directory or any parent, snpm treats the current directory as a single project. Add a workspace file:

packages:
  - "packages/*"
  - "apps/*"

--filter matches nothing

• Selectors are matched against the project's name field in package.json (or, for path selectors, against the project directory).
• Glob patterns need quotes in the shell: --filter "@acme/*".
• For dependency walks (pkg... / ...pkg), make sure the seed name matches a real workspace project.
• [git-ref] runs git diff --name-only <ref> from the workspace root; check that the ref is reachable (git rev-parse <ref> works).

workspace: specifier won't resolve

workspace:* requires that the named package exists in the same workspace. Confirm with snpm list -r or cat packages/*/package.json | jq -r .name.

Registry / auth issues

Authentication failures

• Run snpm config and check default auth and registry auth.
• Verify the env var name — snpm reads SNPM_AUTH_TOKEN, NODE_AUTH_TOKEN, and NPM_TOKEN (in that order).
• For Basic auth, set NPM_CONFIG__AUTH (or SNPM_CONFIG__AUTH) to base64(user:password).

Token leaking to wrong host

snpm only sends the configured token to the registry that owns it. Tarball URLs hosted on a different origin fetch anonymously by design. If a private package is hosted on a CDN under a different domain, configure auth for that CDN host explicitly:

//cdn.mycompany.com/:_authToken=${MYORG_TOKEN}

Lockfile issues

Merge conflicts in snpm-lock.yaml

1. Resolve conflicts in every affected package.json first.
2. Delete snpm-lock.yaml.
3. Run snpm install.

rm snpm-lock.yaml
snpm install
git add snpm-lock.yaml

Use snpm install --fix-lockfile if you want to keep most of the existing resolution.

Lockfile keeps changing in CI

Drop --no-frozen-lockfile from the CI command. The default — snpm install --frozen-lockfile — fails fast when the lockfile drifts so the change shows up as a clear CI error instead of being silently committed.

Patch issues

A patch didn't apply

Run snpm patch list to confirm the patch is registered, and check the patch file actually exists at patches/<package>@<version>.patch. If the package was upgraded since the patch was created, re-run:

snpm patch edit <package>
# make your edits in the temp dir
snpm patch commit <temp dir>

This recreates the patch against the new version.

Audit issues

Audit fails because the registry is down

snpm audit --ignore-registry-errors

This exits with code 0 when the registry's audit endpoint fails, useful when you have other security tooling already running.

Too many low-severity findings

snpm audit --audit-level high

Only high and critical advisories will trigger a non-zero exit.

Reporting bugs

If you're still stuck:

1. Reproduce the issue with snpm --verbose <command> and grab the .snpm.log.
2. Capture snpm config output.
3. File an issue at github.com/binbandit/snpm/issues with:
   • snpm version (snpm --version).
   • Operating system.
   • Minimal repro steps and exact command.
   • Verbose log output.