🚧
【ポート競合】開発環境でよくある接続エラー
はじめに
「アプリが起動しない」「DBに接続できない」「なぜか通信が拒否される」――そんなとき、設定やコードに原因があると決めつけていませんか？
実はそのトラブル、ポートの競合が原因かもしれません。
この記事では、開発現場でよく使われる代表的なポート（3306, 8080, 5432, 6379など）について、競合が起きたときの症状とその見分け方、解決法をご紹介します。
対象者
- Dockerやローカルサービスで環境構築しているエンジニア
- DB接続やサーバー起動エラーに悩んでいる方
- 「原因不明の接続エラー」に何度も悩まされている人
そもそもポート競合とは？
ポートとは、TCP/UDP通信の「入り口」を指します。同じポート番号に複数のプロセスがバインドしようとすると、競合（conflict）が発生し、後から起動したプロセスが失敗します。
例：DockerでMariaDBを起動しようとしたが、ローカルのMySQLがポート3306を占有していたため、起動に失敗。
ポート別：競合時に起きる症状とその原因
ポート3306（MySQL / MariaDB）
- よくある用途：MySQL / MariaDB サーバー
-
競合時の症状：
-
Access deniedやConnection refused - Dockerコンテナが起動しない / 接続できない
- DBクライアントから接続失敗
-
- 原因：macOSのHomebrewでMySQLが自動起動していた
-
確認コマンド：
lsof -i :3306
ポート8080（Webサーバー）
- よくある用途：React/Vue開発サーバー、Spring Boot、Tomcat
-
競合時の症状：
-
EADDRINUSEエラー - ブラウザで
localhost:8080にアクセスできない
-
- 原因：前に起動したままのサーバーや他のアプリが占有
-
確認コマンド：
lsof -i :8080
ポート5432（PostgreSQL）
- よくある用途：PostgreSQL
-
競合時の症状：
could not connect to server: Connection refused- DBクライアントから接続失敗
- 原因：ローカルとDockerのPostgreSQLが競合
-
確認コマンド：
lsof -i :5432
ポート6379（Redis）
- よくある用途：Redisキャッシュ / セッション
-
競合時の症状：
- LaravelやNode.jsのセッション・キューが動かない
-
ECONNREFUSEDやRedis connection error
- 原因：複数のRedisプロセス、またはDockerとの重複
-
確認コマンド：
lsof -i :6379
ポート競合を避けるためにまずやること
- ポート確認を最初に行う
lsof -i :<ポート番号> - 別のポート番号を使うか、競合しているプロセスを終了する
- DockerやKubernetesを使っている場合は、設定を見直す
おわりに
「接続できない」「サーバーが動かない」とき、つい設定ファイルやコードに目が行きがちですが、まずはポートの使用状況を確認することが近道になるケースも多くあります。
私自身もDBクライアントの接続エラーで様々な試行錯誤をして悩んでいたところ、結局原因はポート競合で、最初から lsof コマンドをしていたらすぐに解決できたのに…ということがありました。
本記事が、同じように悩んでいる方の助けになれば幸いです。
株式会社ONE WEDGE
【Serverlessで世の中をもっと楽しく】
ONE WEDGEはServerlessシステム開発を中核技術としてWeb系システム開発、AWS/GCPを利用した業務システム・サービス開発、PWAを用いたモバイル開発、Alexaスキル開発など、元気と技術力を武器にお客様に真摯に向き合う価値創造企業です。
Discussion