shopify theme dev を実行したときに listen EADDRINUSE: address already in use 127.0.0.1:9292 と出る場合は、ローカルの開発サーバーがすでに同じポートを使っています。多くは、前回の shopify theme dev が残っているか、別のプロセスが 9292 を占有しているのが原因です。
このエラーは、テーマのファイル自体が壊れているというより、listen や bind の段階でポートの確保に失敗している状態です。したがって、テーマの中身を先に疑うより、まずは 9292 を使っているプロセスを止めるか、別ポートで起動するのが近道です。
まず結論
最短の対処は次の3つです。
- 同じ端末で
shopify theme devをすでに起動していないか確認する lsofで 9292 を使っているプロセスを確認し、終了する- 必要なら
--portを付けて別ポートで起動する
Shopify CLI のテーマ開発では、既定で http://127.0.0.1:9292 が使われます。ローカルのプレビューを複数立ち上げていたり、ターミナルを閉じただけでサーバーが残っていたりすると、このポート衝突が起きやすくなります。
EADDRINUSE の意味
EADDRINUSE は address already in use の略で、指定したアドレスとポートがすでに使われていることを示します。今回のケースでは、127.0.0.1:9292 に対して別のプロセスが待ち受けているため、Shopify CLI が新しくサーバーを起動できません。
テーマ開発では、shopify theme dev がローカルの開発サーバーを立ち上げ、ブラウザからプレビューできるようにします。この仕組み自体は便利ですが、同じマシンで同じポートを二重に使おうとすると、Node.js 側で listen が失敗し、今回のようなエラーになります。
つまり、エラーの原因は大きく分けて2つです。1つ目は、前回の開発サーバーが終了していないこと。2つ目は、別のアプリや別のテーマ開発用プロセスが 9292 を使っていることです。どちらも、ポートの使用状況を見れば切り分けられます。
具体的な対処
1 まず 9292 を使っているプロセスを確認する
macOS なら、まず lsof で待受中のプロセスを確認します。テーマ開発でよくあるのは、node や shopify 関連のプロセスが残っているケースです。
lsof -nP -iTCP:9292 -sTCP:LISTEN結果が表示されたら、PID 列を見ます。この番号が実際に 9292 を掴んでいるプロセスIDです。複数行表示された場合は、同じポートを複数の経路で見ているだけでなく、関連プロセスが連鎖していることもあるため、落ち着いて確認してください。
2 見つかった PID を終了する
PID が分かったら、まずは通常終了を試します。開発サーバーであれば、kill だけで十分なことが多いです。
kill 12345それでも残る場合は、強制終了を使います。指示書にある通り、kill -9 $(lsof -ti:9292) でも構いません。複数のプロセスがぶら下がっているときは、まとめて終了できるので便利です。
kill -9 $(lsof -ti:9292)ただし、kill -9 は最終手段です。強制終了は状態の保存処理を飛ばすため、もしそのプロセスがファイル書き込み中であれば、中途半端な状態が残ることがあります。まずは Ctrl+C で止められないか、通常の kill で止まるかを確認した方が安全です。
3 同じ端末で動いているなら Ctrl+C で止める
もし shopify theme dev を実行した端末がまだ開いているなら、そこで Ctrl+C を押して停止します。これが一番きれいな止め方です。見た目にはターミナルを閉じていても、tmux や別タブ、別ウィンドウでプロセスが残っていることがあるので注意してください。
複数のテーマを扱っている場合は、どの端末でどのテーマを起動したかが分からなくなりやすいです。そういうときは、ps と grep で関連プロセスを拾うと、残っている開発サーバーを見つけやすくなります。
ps aux | grep 'shopify theme dev'表示された一覧の中から、明らかに現在使っていないものを止めてください。特に Node.js ベースの開発サーバーは、終了し損ねると次回起動時に同じエラーを繰り返します。
別ポートで起動する
9292 をどうしても空けられない場合や、別のテーマを同時に立ち上げたい場合は、--port で起動ポートを変更します。Shopify CLI のテーマコマンドには、テーマのプレビューを別ポートで立てるためのオプションがあります。
shopify theme dev --port=9293この方法なら、既存の 9292 を止めずに新しいプレビューを起動できます。複数のローカルテーマを並行して確認したいときや、他のツールが 9292 を使っているときに便利です。
ただし、ポートを変えると、アクセス先の URL も変わります。ブックマークや共有リンクをそのまま使わず、表示された新しいローカルURLを確認してください。また、チーム内で同じ環境を共有しているなら、どのポートを使うかをメモしておくと混乱を防げます。
再発防止
この手のエラーは、1回解決してもまた起きやすいです。原因の多くは単純で、開発サーバーを止めずにターミナルだけ閉じたこと、あるいは別のプロジェクトを同じポートで起動したことです。運用の仕方を少し整えるだけで、かなり防げます。
- 終了するときは、ターミナルを閉じる前に
Ctrl+Cでshopify theme devを止める - 複数テーマを扱うなら、使うポートを決めておく
- 定期的に
lsof -i:9292で残プロセスを確認する - 不要になったタブやセッションをそのまま放置しない
特に macOS では、ターミナルアプリを閉じても、バックグラウンドに子プロセスが残ることがあります。見た目には終了したつもりでも、実際には 9292 を占有したままということがあるため、停止を明示する運用が重要です。
また、CI や自動化ツール、別のローカルサーバーが動いていると、本人は shopify theme dev しか使っていないつもりでもポートが競合します。テーマ開発のときは、同じマシンで何が動いているかをざっくり把握しておくと、原因の特定が早くなります。
よくある質問
kill -9 は毎回使ってよいですか
毎回使うべきではありません。kill -9 はプロセスに後処理の時間を与えずに止めるため、通常終了より安全性が下がります。まずは Ctrl+C、次に通常の kill、最後に kill -9 という順で考えるのが実務的です。
とはいえ、開発サーバーが応答しない、あるいはプロセスが何度も復活するような状態では、強制終了が必要になります。重要なのは、どのプロセスを止めているかを把握したうえで使うことです。
なぜ 9292 がよく使われるのですか
Shopify CLI のテーマ開発では、既定のローカルプレビューとして 9292 が案内されることが多いためです。公式ドキュメントでも、shopify theme dev は http://127.0.0.1:9292 の開発テーマへのリンクを返し、--port で変更できると説明されています。
つまり 9292 は「たまたま空いている番号」ではなく、テーマ開発用の既定値としてよく使われる番号です。だからこそ、同じマシンで複数の開発セッションを並行させると競合が起きやすくなります。
テーマのファイルが壊れている可能性はありますか
このエラーだけでは、テーマファイルの破損までは判断できません。まずはポート衝突を疑うのが先です。もしポートを変えても起動しない、あるいは別のエラーに変わるなら、その時点で Liquid やアセットの問題を確認すれば十分です。
順番を間違えると、実際はプロセス管理の問題なのにテーマ側を長時間調べることになります。EADDRINUSE が出たときは、まず環境側の切り分けを優先してください。
まとめ
shopify theme dev で listen EADDRINUSE: address already in use 127.0.0.1:9292 が出る場合は、テーマの中身ではなく、ローカルの 9292 ポートがすでに使われていることが原因です。まずは lsof で使用中のプロセスを確認し、Ctrl+C か kill で止めてください。
止められない場合は、kill -9 $(lsof -ti:9292) を使うか、--port で別ポートに切り替えます。複数のテーマを同時に扱うときは、ポート運用を決めておくと再発をかなり減らせます。ポート衝突を先に解消してから、テーマの検証に進むのが最短です。
Comment