docker compose watchで「cannot take exclusive lock」が出る原因

  • Docker
  • Docker Compose

この記事は、構成と文章の整理にAIを使っています。
あくまで読みやすくするための補助で、内容そのものをAIにすべて任せて書いているわけではありませんが、ところどころ相談しながら整えています。

エラーの内容

docker compose watch を実行したら以下のエラーが出た。

cannot take exclusive lock for project "example-project": process with PID 11691 is still running

docker compose up とかじゃなくて watch 特有のやつ。

原因

docker compose watch はプロジェクトごとに排他ロックを取る。ロックの実体はPIDファイルで、/run/user/<UID>/<プロジェクト名>.pid みたいな場所に置かれるらしい(実機のパスは環境によって多少違うかもしれない、未確認)。中身は起動中の watch プロセスのPID。

起動時にこのファイルに書かれたPIDが生きてるかチェックして、生きてたら「もう動いてるから無理」って弾かれる仕組み。

今回のケースは単純で、別のターミナルですでに docker compose watch を起動したまま、もう一枚ターミナルを開いて同じプロジェクトに対して watch を実行してた。watch はフォアグラウンドで動き続けるプロセスだから、二重起動するとこのエラーになる。

対処

まずPID 11691 が本当に docker compose watch かどうか確認する。

ターミナル
ps -p 11691 -o pid,ppid,command
  PID  PPID COMMAND
11691 12345 docker compose watch

こう出れば当たり。中身を確認せずにkillすると、PIDが別プロセスに再利用されてて無関係なプロセスを巻き込む可能性があるので注意。

確認できたら通常終了。

ターミナル
kill 11691

数秒待って残ってないか確認。

ターミナル
ps -p 11691

まだ残ってたら強制終了。

ターミナル
kill -9 11691

これで大体直る。あとは docker compose watch を再実行すればOK。

killしても直らない場合

GitHubのissueを見ると、プロセスをkillしてもロックエラーが解消しないケースが報告されてる。ロックファイル自体が壊れてるのかチェック処理側の問題なのかは分からない(未確認)。

その場合はDockerエンジン自体を再起動する。Linuxなら:

ターミナル
sudo service docker restart

Docker Desktop(Mac/Windows)の場合はこのコマンドは使えないので、Docker Desktopアプリごと再起動する必要がある。

流れ

flowchart TD
    A[排他ロックエラー発生] --> B[ps -p PIDでプロセス確認]
    B -->|docker compose watchだった| C[kill PID]
    B -->|別プロセスだった| G[PIDの誤認、原因を再調査]
    C --> D[数秒待ってps -p PIDで再確認]
    D -->|消えた| E[docker compose watch 再実行]
    D -->|残ってる| F[kill -9 PID]
    F --> E
    E -->|それでもロックエラー| H[Dockerエンジン自体を再起動]

watch は常駐プロセスだから二重起動に弱い。エラーが出たらいきなりkillせず、まずPIDの中身を確認してから対処するのが安全。