できない.dev

pnpm install が「ERR_PNPM_PEER_DEP_ISSUES」で失敗する（peer 依存）

ERR_PNPM_PEER_DEP_ISSUES は、満たされない・競合する peer 依存を pnpm が厳格に扱って install を止めるサイン。
バージョンを実際に直すのが本筋で、誤検知は auto-install-peers や peerDependencyRules で個別に対処する。

#pnpm #peer-dependencies #strict-peer-dependencies #auto-install-peers #npmrc

公開: 更新:

実行例あり（2026-10-01 に実環境で検証）

要約

ERR_PNPM_PEER_DEP_ISSUES は、パッケージが要求する peer 依存（同じ階層に居てほしい依存）が満たせない、あるいはバージョンが競合しているときに pnpm が install を止めるエラー。
pnpm は peer の扱いが厳格で（How peers are resolved（新しいタブで開く））、strict-peer-dependencies が有効だと警告ではなくエラーになる。
本筋は実際のバージョン不一致を直すこと。
直せない誤検知は設定で個別に黙らせる。

実行例

pnpm 12.8.1 で react@19 と use-sync-external-store@1.2.0 を一緒に入れると、pnpm-workspace.yaml の strictPeerDependencies: true では ERR_PNPM_PEER_DEP_ISSUES で止まったが、同じ指定を .npmrc に書いた場合は警告だけで入った。
react@18 に合わせるか pnpm-workspace.yaml の peerDependencyRules で許可すると通り、package.json の pnpm フィールドに書いた許可は読まれずエラーのままだった。

$ pnpm --version
12.8.1
$ cat pnpm-workspace.yaml
strictPeerDependencies: true
$ pnpm add react@19 use-sync-external-store@1.2.0
Progress: resolved 0, reused 0, downloaded 1, added 0
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: /root/.local/share/pnpm/store/v11
  Virtual store is at:             node_modules/.pnpm
Packages: +2
++
Progress: resolved 2, reused 0, downloaded 2, added 2, done
[ERR_PNPM_PEER_DEP_ISSUES] Unmet peer dependencies
 
✕ unmet peer react
  Installed: 19.3.0
  Wanted:
    "^16.8.0 || ^17.0.0 || ^18.0.0":
      use-sync-external-store@1.2.0
hint: To disable failing on peer dependency issues, add the following to pnpm-workspace.yaml in your project root:
 
  strictPeerDependencies: false
$ echo $?
1
$ cat .npmrc
strict-peer-dependencies=true
$ pnpm add react@19 use-sync-external-store@1.2.0
Progress: resolved 0, reused 1, downloaded 0, added 0
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: /root/.local/share/pnpm/store/v11
  Virtual store is at:             node_modules/.pnpm
Packages: +2
++
Progress: resolved 2, reused 2, downloaded 0, added 2, done
[WARN] Issues with peer dependencies found. Run "pnpm peers check" to list them.
 
dependencies:
+ react 19.3.0
+ use-sync-external-store 1.2.0
 
Done in 27ms using pnpm v12.8.1
$ echo $?
0
$ pnpm add react@18 use-sync-external-store@1.2.0
Progress: resolved 0, reused 1, downloaded 0, added 0
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: /root/.local/share/pnpm/store/v11
  Virtual store is at:             node_modules/.pnpm
Packages: +4
++++
Progress: resolved 4, reused 1, downloaded 3, added 4, done
 
dependencies:
+ react 18.3.1
+ use-sync-external-store 1.2.0
 
Done in 212ms using pnpm v12.8.1
$ echo $?
0
$ cat pnpm-workspace.yaml
strictPeerDependencies: true
peerDependencyRules:
  allowedVersions:
    react: "19"
$ pnpm add react@19 use-sync-external-store@1.2.0
Progress: resolved 0, reused 1, downloaded 0, added 0
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: /root/.local/share/pnpm/store/v11
  Virtual store is at:             node_modules/.pnpm
Packages: +2
++
Progress: resolved 2, reused 2, downloaded 0, added 2, done
 
dependencies:
+ react 19.3.0
+ use-sync-external-store 1.2.0
 
Done in 21ms using pnpm v12.8.1
$ echo $?
0
$ cat package.json
{
  "name": "peer-demo",
  "version": "1.0.0",
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": { "react": "19" }
    }
  }
}
$ pnpm add react@19 use-sync-external-store@1.2.0
[WARN] The "pnpm" field in package.json is no longer read by pnpm. The following keys were ignored: "pnpm.peerDependencyRules". See https://pnpm.io/settings for the new home of each setting.
Progress: resolved 0, reused 1, downloaded 0, added 0
Packages are hard linked from the content-addressable store to the virtual store.
  Content-addressable store is at: /root/.local/share/pnpm/store/v11
  Virtual store is at:             node_modules/.pnpm
Packages: +2
++
Progress: resolved 2, reused 2, downloaded 0, added 2, done
[ERR_PNPM_PEER_DEP_ISSUES] Unmet peer dependencies
 
✕ unmet peer react
  Installed: 19.3.0
  Wanted:
    "^16.8.0 || ^17.0.0 || ^18.0.0":
      use-sync-external-store@1.2.0
hint: To disable failing on peer dependency issues, add the following to pnpm-workspace.yaml in your project root:
 
  strictPeerDependencies: false
$ echo $?
1

— 2026-10-01 時点の出力

検証環境

検証日
実行環境
node:22Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 22.23.3
  • npm 10.9.9
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

よくある原因

  1. strict 設定: strict-peer-dependencies が true で、未充足・不一致をすべてエラーにしている。
  2. バージョン不一致: 例えばプラグインが react@^18 を要求しているのに react@19 が入っている。
  3. 親の追従遅れ: peer を要求する側が更新されておらず、新しいメジャーに対応していない。
  4. 自動補完オフ: auto-install-peers を切っていて、不足 peer が自動で入らない。

解決策

1. まず本当に直す

不足・競合している peer を正しいバージョンで入れる。
これが根治。

pnpm add react@18 react-dom@18

エラーメッセージに「どの依存がどのレンジを要求しているか」が出るので、それに合わせる。

2. 自動インストールと厳格度（設定）

peer を自動で入れたい、または一時的に警告へ下げたいときは設定する（Settings（新しいタブで開く））。

# pnpm-workspace.yaml（プロジェクトのルート）
autoInstallPeers: true
strictPeerDependencies: false

pnpm 11 からは、pnpm 固有の設定は pnpm-workspace.yaml（キーは camelCase）にしか書けない。.npmrc は認証とレジストリの設定しか読まれないため、pnpm 10 までのように .npmrc に書いた auto-install-peers=true や strict-peer-dependencies=true は、警告も出ずに無視される（Migrating from v10（新しいタブで開く））。

3. 個別に許可する（誤検知向け）

追従待ちなど「動くと分かっている」ものは pnpm-workspace.yaml で限定的に許可する。

peerDependencyRules:
  allowedVersions:
    react: "19"
  ignoreMissing:
    - "@types/react"

pnpm 10 までは package.json の pnpm フィールドにも書けたが、pnpm 11 からは読まれない。
書いたままにすると「The "pnpm" field in package.json is no longer read by pnpm」という警告が出るだけで許可は効かず、strictPeerDependencies: true ならエラーのまま止まる。

この記事は役立ちましたか？