Claude Codeを使用してReact/Vue.jsとPython(FastAPI/Flask)の統合開発をしていた際、エージェントによる自動修正ループ（Plan-and-Execute）を回そうとしたところで「ポートが既に使用されている」というエラーにハマったので備忘録として残します。
この記事でわかること
- Claude CodeでのEADDRINUSEエラーの根本原因
- AI自動開発中に発生するゾンビプロセスの対処法
- ポート競合を自動で回避する開発サーバー起動コマンドの書き換え
目次
[現象] EADDRINUSEエラーでAIの修正ループが停止する
Claude Codeが「修正→テスト」のサイクルを自律的に繰り返している際、以下のようなエラーを出力してプロセスが停止することがあります。
Error: listen EADDRINUSE: address already in use :::8000 (or :::5173).
Claude Code execution stalled due to port conflict.[環境]
- Frontend: React / Vue.js (Vite等)
- Backend: Python (FastAPI / Flask)
- Tool: Claude Code
[原因] AIの高速修正ループとOSのソケット解放遅延
このエラーの根本原因は、Claude Codeの内部プロセス管理にあります。AIが修正後の再実行を試みる際、既存のサブプロセス（ゾンビプロセス）を完全にクリーンアップできず、同じポートで再起動を試みることで発生します。特にAIが高速でループを回す場合、OS側のソケット解放が追いつかないことが要因です。
[解決策] 起動コマンドに強制解放を組み込む
開発サーバーの起動コマンドを、ポートを強制的に解放してから実行するように変更します。
| 対象 | Before（修正前） | After（修正後） |
|---|---|---|
| Python (FastAPI) | uvicorn main:app --reload | fuser -k 8000/tcp || true && uvicorn main:app --host 0.0.0.0 --port 8000 |
| Frontend (Vite) | npm run dev | fuser -k 5173/tcp || true && npm run dev |
AIへのカスタムインストラクション追加
プロジェクトの.claudecodeconfigやカスタムインストラクションに以下の制約を追加し、AI側にクリーンアップの責務を持たせることも有効です。
- サーバー起動前には、必ず該当ポート（8000や5173）のプロセスをKillするコマンド（fuser -kなど）を実行してください。[まとめ]
AI自動開発をスムーズに進めるためには、環境構築における「プロセスの掃除」が鍵となります。ゾンビプロセスの発生を前提としたコマンド構成にすることで、Claude Codeの自律的な開発を止めずに継続させることが可能です。
