Zoltan Kochan
4e6351952d
Correct the v12 guides from agent-skills.md through lockfile.md against pnpm/crates, and fix the same wrong text on the v11 twins where pnpm11 confirms it. Part of pnpm/tasks#191. Wrong claims (both versions): - configuring: the global auth file is auth.ini, not rc; list the npm_config_* exceptions (workspace dir, userconfig, URL-scoped auth). - config-dependencies: the hook import used an invalid ESM specifier. - docker: Example 3 ran fetch --prod and built without an offline install or pnpm-workspace.yaml. - errors: drop MISMATCHED_RELEASE_CHANNEL, describe INVALID_NODE_VERSION through nodeVersion, PEER_DEP_ISSUES needs strictPeerDependencies. - faq: no lockfile deletion after a readPackage hook, default store order, junctions depend on symlink privilege. - filtering: `!./lib` matches one project; use `!./lib/**`. - git branch lockfiles: every non [A-Za-z0-9_.-] character becomes `!`, the name is lowercased, merging deletes branch lockfiles, "or" patterns. - git-worktrees: remove the nonexistent worktree:new and shell/wt.sh. - global-packages: orphaned dirs are cleaned by add -g (and update -g in v12), not store prune; document that add -g replaces every group that contains the package. - how-peers-are-resolved: current peer directory names. - completion: built-in completion already covers --filter and scripts. - feature-comparison: broken JSR anchor. Wrong claims (v12 only): - cargo: cargo.indexUrl fails the parse, overrides apply to adding only, merge the duplicated Cargo index section into Registries. - global-virtual-store: pnx keeps its own virtual store (dlx part only; the global-install claims are left for a separate decision). - installation: the npm package installs on Node.js 18, only get-pnpm needs 22.13; trim unverified compatibility rows. Missing facts (v12): agent-skills group filtering and naming, catalogs (catalogs.default, pnx, --save-catalog, error codes), cargo recursive add, build-std, resolution keys, completion zsh/pwsh setup, config dependency location and error codes, include error codes, CI opt-outs and pnpm ci, finders on list, filtering settings and --no-fail-if-no-match, global install refusals, trust for npm-registry package managers, Rust shims, overrides link from aliases. Stale history (v12): drop v11/v10 version markers and "since v11" narration in continuous-integration, filtering, finders, git-worktrees, global-packages, global-virtual-store, how-peers-are-resolved, lockfile, completion, configuring. Review follow-up: the Node.js compatibility table keeps the pnpm 10 column; Docker Example 3 builds with all dependencies in a build stage and ships only production dependencies, with the pnpm-workspace.yaml caveat (both versions); catalogs keep the bare-path form; v11 global packages name `pnpm update -g` as cleaning orphans too; the cargo build-std note says when rust-src must be listed. Second review: build-std needs a non-empty list; the Docker fetch layer also depends on the project settings; branch lockfile names keep only ASCII characters; the conflict merge needs both sides to parse; Rust shims and package managers are default globalShims participants; pnpm self-update also cleans orphaned global groups; v12 pnpm login writes tokens to config.yaml; legacyDirFiltering keeps the subtree wording (the v12 mismatch is pnpm/tasks#196); the v12 Docker example copies the files that `include` names before pnpm fetch.
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
---
|
|
id: errors
|
|
title: Error Codes
|
|
---
|
|
|
|
## ERR_PNPM_TASK_CYCLE
|
|
|
|
A recursive run's task graph contains a dependency cycle. The error lists the
|
|
participating tasks as `<project>#<script>` identifiers.
|
|
|
|
Remove or change the cycle under [`tasks`](./workspace-task-orchestration.md).
|
|
If it is deliberate, set
|
|
[`ignoreWorkspaceCycles`](./workspaces.md#ignoreworkspacecycles) to `true` to
|
|
downgrade the error to a warning and run the cycle's tasks without a guaranteed
|
|
order.
|
|
|
|
## ERR_PNPM_UNEXPECTED_STORE
|
|
|
|
A modules directory is present and is linked to a different store directory.
|
|
|
|
If you changed the store directory intentionally, run `pnpm install` and pnpm will reinstall the dependencies using the new store.
|
|
|
|
## ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE
|
|
|
|
A project has a workspace dependency that does not exist in the workspace.
|
|
|
|
For instance, package `foo` has `bar@1.0.0` in the `dependencies`:
|
|
|
|
```json title="package.json"
|
|
{
|
|
"name": "foo",
|
|
"version": "1.0.0",
|
|
"dependencies": {
|
|
"bar": "workspace:1.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
However, there is only `bar@2.0.0` in the workspace, so `pnpm install` will fail.
|
|
|
|
To fix this error, all dependencies that use the [workspace protocol] should be updated to use versions of packages that are present in the workspace. This can be done either manually or using the `pnpm -r update` command.
|
|
|
|
[workspace protocol]: ./workspaces.md#workspace-protocol-workspace
|
|
|
|
## ERR_PNPM_PEER_DEP_ISSUES
|
|
|
|
With [`strictPeerDependencies`](./settings/peer-dependencies.md#strictpeerdependencies) enabled, `pnpm install` fails if the project has unresolved peer dependencies or the peer dependencies are not matching the wanted ranges. To fix this, install the missing peer dependencies.
|
|
|
|
You may also selectively ignore these errors using the [peerDependencyRules.ignoreMissing] and [peerDependencyRules.allowedVersions] settings.
|
|
|
|
[peerDependencyRules.ignoreMissing]: settings/peer-dependencies.md#peerdependencyrulesignoremissing
|
|
[peerDependencyRules.allowedVersions]: settings/peer-dependencies.md#peerdependencyrulesallowedversions
|
|
|
|
## ERR_PNPM_OUTDATED_LOCKFILE
|
|
|
|
This error happens when installation cannot be performed without changes to the lockfile. This might happen in a CI environment if someone has changed a `package.json` file in the repository without running `pnpm install` afterwards. Or someone forgot to commit the changes to the lockfile.
|
|
|
|
To fix this error, run `pnpm install` and commit the changes to the lockfile.
|
|
|
|
## ERR\_PNPM\_TARBALL\_INTEGRITY
|
|
|
|
This error indicates that the downloaded package's tarball did not match the expected integrity checksum.
|
|
|
|
If you use the npm registry (`registry.npmjs.org`), then this usually means that the integrity in your lockfile is incorrect.
|
|
This might happen if a lockfile had badly resolved merge conflicts.
|
|
|
|
If you use a registry that allows to override existing versions of a package, then it might mean that in your local metadata cache you have the integrity checksum of an older version of the package. In this case, you should run `pnpm store prune`. This command will remove your local metadata cache. Then you can retry the command that failed.
|
|
|
|
But also be careful and verify that the package is downloaded from the right URL. The URL should be printed in the error message.
|
|
|
|
## ERR_PNPM_REGISTRY_NAME_MISMATCH
|
|
|
|
The registry answered a request for one package with the metadata of a different package. pnpm stops instead of installing the package under a name the registry was not asked about.
|
|
|
|
Check that the registry configured for the package, or for its scope, is correct. A misconfigured proxy or a registry that serves the wrong document can cause this error.
|
|
|
|
## ERR_PNPM_INVALID_NODE_VERSION
|
|
|
|
The [`nodeVersion`](./settings/cli.md#nodeversion) setting is not an exact semver version, such as `22.22.3`.
|