wrangler devがAddress already in useで起動しない時のポート変更手順

npx wrangler dev を実行したら Address already in use で止まってしまう——これは起動しようとしたポートが、別のプロセスにすでに握られている状態です。この記事は、そのエラーを「占有プロセスの特定 → ポートの変更 → 設定ファイルへの固定」の順で片づけたい開発者向けです。コマンドと設定値をそのまま貼れる形で並べます。バージョンや既定値は執筆時点（2026年10月）のものです。

なぜ「Address already in use」が出るのか

このメッセージの正体は、OS が返す EADDRINUSE というエラーです。あるポートで待ち受け（listen）できるプロセスは原則ひとつだけで、そこへ2つ目が bind しようとすると弾かれます。

wrangler dev の既定ポートは 8787 です（公式ドキュメントによると、ローカル開発サーバーのデフォルトは 8787）。つまり次のどれかが起きています。

• 前回の wrangler dev がターミナルを閉じたあとも裏で生き残っている
• 別のプロジェクトの wrangler dev を同時に立ち上げている
• まったく別のアプリ（別のdevサーバーなど）が 8787 を使っている
• 後述する inspector ポート 9229 のほうが衝突している

どれが原因かで打つ手が変わるので、まずは「誰が握っているか」を特定します。

まず原因のポートを特定する

占有しているプロセスを調べます。OS ごとにコマンドが違います。

Linux の場合:

# ポート8787を listen しているプロセスを表示
ss -tlnp | grep ':8787'
# ss が無ければ
lsof -i :8787

macOS の場合:

lsof -i :8787

出力の末尾（pid=12345 や PID 列）に、そのポートを握っているプロセスIDが出ます。ここで正体を見てから、次の2つの方針どちらかを選びます。

解決策1: wrangler dev のポートを変える

一番安全なのはこちらです。相手に触らず、wrangler dev 側を空いているポートへ逃がします。

一時的に変えるなら、起動時にフラグを渡します。

# 8788 に変更して起動
npx wrangler dev --port 8788
# 短縮形も同じ意味
npx wrangler dev -p 8788

毎回指定するのが面倒なら、設定ファイルに固定します。wrangler.jsonc の場合:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-09-01",
  "dev": {
    "ip": "localhost",
    "port": 8788
  }
}

wrangler.toml 派ならこう書きます。

[dev]
ip = "localhost"
port = 8788

「空いていればどれでもいい」なら、ポート 0 を指定する方法があります。一般に、ポート番号として 0 を渡すとOSが空いているポートを自動で割り当てます。

npx wrangler dev --port 0

この挙動や、実際に割り当てられたポートがどこに表示されるかはバージョンや環境によって異なる場合があるため、起動ログを確認して実際のポートを把握してください。固定したい運用（リバースプロキシやCloudflare Tunnelの向き先を決め打ちしたい場合など）には向かないので、その時は数値で固定してください。

解決策2: 占有しているプロセスを止める

特定したPIDが「閉じ忘れた前回のwrangler」のように不要だと分かっているなら、止めてしまうのが早いです。

# さきほど調べたPIDを指定
kill 12345
# それでも残るなら強制終了
kill -9 12345

ここで注意したいのが、pkill -f wrangler のような「名前でまとめて殺す」やり方です。コマンド文字列にマッチするため、関係ないプロセスや、場合によっては今いるシェルまで巻き込むことがあります。ポートからPIDを引いて、そのPIDだけを止めるほうが事故が少ないです。環境によってプロセスの残り方は異なります。

inspector ポート(9229)の落とし穴

--port を変えたのにまだ Address already in use が出る——これは wrangler dev がもう1つ別のポートを開いているからです。デバッガ接続用の inspector ポート で、公式ドキュメントによると既定は 9229 です。メインの 8787 を避けても、9229 が別プロセス（別のNode系デバッガなど）とぶつかっていれば同じエラーになります。

こちらは --inspector-port で逃がせます。

npx wrangler dev --port 8788 --inspector-port 9230

設定ファイルに固定したい場合は、前述の dev セクションに inspector_port を足します。複数プロジェクトを同時に wrangler dev したいときは、メインとinspectorの両方をプロジェクトごとにずらしておくと、この手のぶつかりをまとめて避けられます。

調べるコマンドは 8787 のときと同じで、ポート番号だけ置き換えます。

lsof -i :9229

まとめ

Address already in use は「そのポートを別の誰かが先に使っている」という素直なサインです。やることは、ss/lsof で握っている相手を特定し、相手を残すなら --port（＋必要なら --inspector-port）で逃がす、不要なら該当PIDだけを kill する、の二択です。再発させたくなければ wrangler.jsonc の dev にポートを書いて固定しておきましょう。

次の一手として、いま開発中のプロジェクトの wrangler.jsonc に dev.port と inspector_port を書き込んで固定しておくことをおすすめします。ローカルで固めたポートを本番ドメインへどう振り分けるかは、Cloudflare Tunnelのingressで複数サブドメインを振り分ける設定例もあわせて読むと流れがつかめます。