【pnpm】ERR_PNPM_UNEXPECTED_STORE Unexpected store location

はじめに

最近話題のpnpm × Next.js × Dockerを使ってパッケージのインストールをしていたとき，このエラーに詰まったので備忘録として書いておきます．

結論は，pnpmの仕組みを理解しないとエラーを起こすということです．

間違いを含んでいる可能性があるため，ご利用の際はご注意ください．
間違いを発見された方は，コメント等で指摘いただきたいです🙇

エラー

エラーメッセージ

Packages: +170
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 170, reused 59, downloaded 111, added 170, done
✔ Checking registry.
⠸ Installing dependencies.
Something went wrong. Please check the error below for more details.
If the problem persists, please open an issue on GitHub.

Command failed with exit code 1: pnpm add <package_name>
 ERR_PNPM_UNEXPECTED_STORE  Unexpected store location

The dependencies at "/Users/user_name/your_project_path/node_modules" are currently linked from the store at "/app/.pnpm-store/v3".

pnpm now wants to use the store at "/Users/user_name/Library/pnpm/store/v3" to link dependencies.

If you want to use the new store location, reinstall your dependencies with "pnpm install".

You may change the global store location by running "pnpm config set store-dir <dir> --global".
(This error may happen if the node_modules was installed with a different major version of pnpm)

エラーを含むdocker-compose.yml

❌ docker-compose.yml

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - .pnpm-store/v3:/app/node_modules # ←これがおかしい
    stdin_open: true
    tty: true
    command: pnpm run dev

原因と結果

そもそもpnpmは，storeというパッケージの依存関係を集約しておき，必要なプロジェクトはそれを随時参照するという方針を取っています．従来のパッケージ管理であったnpm, yarnよりも何倍も軽量に管理できることで話題となっています．
したがって，それらを貯めておく.pnpm-storeというディレクトリが生成されます．

今回のエラー原因はローカルにある.pnpm-storeと，コンテナ内にある.pnpm-storeを共有していなかったことです．コンテナの/app/node_modulesを指定していたため，ローカル環境とコンテナ間で異なるストアにアクセスしようとした際にリンクの競合が発生したことが原因だと考えられます．（pnpmの意味がないw）

更新後のdocker-compose.yml

そこでdocker-compose.ymlを以下のように修正すると解決しました．

⭕️ docker-compose.yml

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - ./.pnpm-store/v3:/app/.pnpm-store/v3 # ←ここ！
    stdin_open: true
    tty: true

Dockerfile

プロトタイプ段階なので，Dockerfileは適当です．

FROM node:23-alpine

WORKDIR /app

RUN npm install -g pnpm

COPY . .

RUN pnpm install --frozen-lockfile

EXPOSE 3000

CMD ["pnpm", "dev"]

まとめ

今回のエラーは，pnpmのstoreの仕組みを理解していなかったために発生しました．ローカルとDocker間でstoreを共有することで解決しました．技術の背景情報などもある程度知っておく重要性を再認識しました．また，DockerfileでCOPYすべきでないファイルの指定など勉強したいと思います．