# Troubleshooting (/docs/troubleshooting) A first-aid kit for the most common problems. When something is off, the fastest signal is usually `snpm config` plus `snpm --verbose `. Diagnostics [#diagnostics] ```bash 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 # explain why a transitive package is installed ``` Installation issues [#installation-issues] snpm: command not found [#snpm-command-not-found] If you installed via npm: make sure the npm global bin directory is on `PATH`. Try: ```bash npm bin -g export PATH="$(npm bin -g):$PATH" ``` If you installed via `cargo install`, add the cargo bin directory: ```bash export PATH="$HOME/.cargo/bin:$PATH" ``` cargo install --path snpm-cli fails [#cargo-install---path-snpm-cli-fails] Update the Rust toolchain: ```bash rustup update stable ``` Then rebuild from a clean target dir: ```bash cargo clean cargo install --path snpm-cli --force ``` Pinned packageManager version not found [#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: ```bash snpm --switch-ignore-package-manager install ``` Or run with a known good version: ```bash snpm --switch-version 2026.5.16 install ``` Install issues [#install-issues] --frozen-lockfile fails [#--frozen-lockfile-fails] The lockfile is missing or out of sync with `package.json`. Locally: ```bash snpm install git add snpm-lock.yaml git commit -m "Refresh lockfile" ``` If you only want to re-resolve drifted entries: ```bash snpm install --fix-lockfile ``` Install scripts were blocked [#install-scripts-were-blocked] snpm prints which packages had their scripts blocked. Add the trusted ones to the allow-list: ```bash 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: ```yaml title="snpm-workspace.yaml" onlyBuiltDependencies: - esbuild - sharp ``` "package not found" / 404 [#package-not-found--404] * Check the package name and version: `snpm dlx npm view `. * 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 [#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](/docs/ci-cd)). * Re-check the lockfile mode — `--frozen-lockfile` skips network resolution entirely when the lockfile is valid. Recently published packages are skipped [#recently-published-packages-are-skipped] `SNPM_MIN_PACKAGE_AGE_DAYS` is filtering them out. Confirm with: ```bash snpm config | grep "min package age" ``` Lower the threshold or unset the variable for the current shell. Workspace issues [#workspace-issues] Workspace not detected [#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: ```yaml title="snpm-workspace.yaml" packages: - "packages/*" - "apps/*" ``` --filter matches nothing [#--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 ` from the workspace root; check that the ref is reachable (`git rev-parse ` works). workspace: specifier won't resolve [#workspace-specifier-wont-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 [#registry--auth-issues] Authentication failures [#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 [#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: ```ini title=".snpmrc" //cdn.mycompany.com/:_authToken=${MYORG_TOKEN} ``` Lockfile issues [#lockfile-issues] Merge conflicts in snpm-lock.yaml [#merge-conflicts-in-snpm-lockyaml] 1. Resolve conflicts in every affected `package.json` first. 2. Delete `snpm-lock.yaml`. 3. Run `snpm install`. ```bash 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 [#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 [#patch-issues] A patch didn't apply [#a-patch-didnt-apply] Run `snpm patch list` to confirm the patch is registered, and check the patch file actually exists at `patches/@.patch`. If the package was upgraded since the patch was created, re-run: ```bash snpm patch edit # make your edits in the temp dir snpm patch commit ``` This recreates the patch against the new version. Audit issues [#audit-issues] Audit fails because the registry is down [#audit-fails-because-the-registry-is-down] ```bash 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 [#too-many-low-severity-findings] ```bash snpm audit --audit-level high ``` Only `high` and `critical` advisories will trigger a non-zero exit. Reporting bugs [#reporting-bugs] If you're still stuck: 1. Reproduce the issue with `snpm --verbose ` and grab the `.snpm.log`. 2. Capture `snpm config` output. 3. File an issue at [github.com/binbandit/snpm/issues](https://github.com/binbandit/snpm/issues) with: * snpm version (`snpm --version`). * Operating system. * Minimal repro steps and exact command. * Verbose log output.