错误码

An error pnpm raises carries a code that starts with ERR_PNPM_. The code is printed with the error message. A script that reacts to a failure should match on the code, because the message may change between releases and the code does not.

The codes are listed in alphabetical order. A code that is not listed here is explained by its own message.

ERR_PNPM_FROZEN_LOCKFILE_WITH_OUTDATED_LOCKFILE#

A frozen install (pnpm install --frozen-lockfile, the default in CI) found that the boot document of pnpm-lock.yaml is not up to date. The boot document records the config dependencies and the pinned package manager. It changes when configDependencies in pnpm-workspace.yaml changes, or when the pnpm version pinned in package.json changes.

Run pnpm install without --frozen-lockfile and commit the updated lockfile.

ERR_PNPM_HOIST_PATTERN_DIFF#

pnpm add, pnpm remove, pnpm update, or an install that selects only some workspace projects found a modules directory that was installed with a different hoistPattern.

Run pnpm install to recreate the modules directory with the new hoistPattern.

ERR_PNPM_IGNORED_BUILDS#

The install skipped the build scripts of one or more dependencies, because allowBuilds does not allow them, and strictDepBuilds is on. The message lists the packages whose scripts were skipped.

Run pnpm approve-builds to allow the builds you trust. To install without failing on skipped builds, set strictDepBuilds to false.

ERR_PNPM_INVALID_NODE_VERSION#

The nodeVersion setting is not an exact semver version, such as 22.22.3.

ERR_PNPM_LOCKFILE_CONFIG_MISMATCH#

A frozen install found that a setting recorded in pnpm-lock.yaml differs from the current configuration. The message names the setting. The lockfile records overrides, patchedDependencies, catalogs, ignoredOptionalDependencies, the checksums of packageExtensions and the pnpmfile, and the resolution settings in its settings block, such as autoInstallPeers and dedupePeers.

Run pnpm install without --frozen-lockfile and commit the updated lockfile.

ERR_PNPM_NODE_LINKER_DIFF#

pnpm add, pnpm remove, pnpm update, or an install that selects only some workspace projects found a modules directory that was installed with a different nodeLinker.

Run pnpm install to recreate the modules directory with the new nodeLinker.

ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE#

项目具有工作空间中不存在的工作空间依赖。

例如，包 foo 在 dependencies 中拥有 bar@1.0.0：

package.json
{
  "name": "foo",
  "version": "1.0.0",
  "dependencies": {
    "bar": "workspace:1.0.0"
  }
}

但是，工作区中只有 bar@2.0.0，所以 pnpm install 将失败。

要修复此错误，所有使用 [工作空间协议][workspace protocal] 的依赖项需要被更新至当前工作空间中的版本。这可以手动完成，也可以使用 pnpm -r update 命令完成。

ERR_PNPM_NO_OFFLINE_META#

pnpm runs with --offline, and the metadata cache has no entry for a package it has to resolve. The message names the package and the cache file it looked for.

Run the command without --offline once, so pnpm downloads the metadata. --prefer-offline uses the cache when it can and downloads what is missing.

ERR_PNPM_OUTDATED_LOCKFILE#

如果不更改锁文件无法执行安装，则会发生此错误。如果有人更改了存储库中的 package.json 文件，之后没有运行 pnpm install，这可能会发生在 CI 环境中。或者有人忘记提交锁文件的更改。

To fix this error, run pnpm install and commit the changes to the lockfile.

ERR_PNPM_PEER_DEP_ISSUES#

With strictPeerDependencies enabled, pnpm install fails if the project has unresolved peer dependencies or the peer dependencies are not matching the wanted ranges. 要解决此问题，请安装缺少的对等依赖项。

您也可以使用 peerDependencyRules.ignoreMissing 和 peerDependencyRules.allowedVersions 设置选择性忽略这些错误。

ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF#

pnpm add, pnpm remove, pnpm update, or an install that selects only some workspace projects found a modules directory that was installed with a different publicHoistPattern.

Run pnpm install to recreate the modules directory with the new publicHoistPattern.

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

此错误表示下载的软件包的 tarball 与预期的完整性校验和不匹配。

If you use the npm registry (registry.npmjs.org), then this usually means that the integrity in your lockfile is incorrect. 如果锁文件解析时错误地合并冲突，则可能会发生这种情况。

如果使用允许覆盖包的现有版本的注册源，则可能意味着在本地元数据缓存中有旧版本软件包的完整性校验。在这种情况下，你应该运行 pnpm store prune。此命令将删除你的本地元数据缓存。然后你可以重试失败的命令。

但是也要小心并验证软件包是否从正确的 URL 下载。错误消息中应该打印 URL。

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. If it is deliberate, set ignoreWorkspaceCycles to true to downgrade the error to a warning and run the cycle's tasks without a guaranteed order.

ERR_PNPM_UNEXPECTED_STORE#

模块目录存在并链接到了不同的存储目录。

如果你有意更改了存储目录，请运行 pnpm install ，pnpm 将使用新存储重新安装依赖。

ERR_PNPM_UNSUPPORTED_ENGINE#

A project's engines.node or engines.pnpm range, or a dependency's engines.node range, does not accept the current version. The message names the package, the wanted range, and the current version.

A project's incompatible engines.pnpm always raises this error. For engines.node, pnpm raises it only with engineStrict enabled. Without it, an incompatible engines.node in the project or a required dependency produces a warning.

To fix this error, switch to a Node.js or pnpm version the package accepts, or turn engineStrict off for an engines.node mismatch.

ERR_PNPM_VIRTUAL_STORE_DIR_MAX_LENGTH_DIFF#

pnpm add, pnpm remove, pnpm update, or an install that selects only some workspace projects found a modules directory that was installed with a different virtualStoreDirMaxLength.

Run pnpm install to recreate the modules directory with the new virtualStoreDirMaxLength.

ERR_PNPM_WORKSPACE_PKG_NOT_FOUND#

A project declares a dependency with the workspace protocol, but no project in the workspace has that name. The message names the project, the dependency, and its specifier.

Check the spelling of the dependency name, and check that the project it refers to is matched by the packages patterns in pnpm-workspace.yaml.