ECONNREFUSED（Connection refused）

一言でいうと（このエラーが何を意味するか）

ECONNREFUSED（メッセージ文言は connect: Connection refused）は、接続先のIPアドレスとポートまでパケットは届いたのに、そのポートで待ち受けている（LISTEN 状態の）プロセスが存在しなかったことを示すエラーです。POSIX の connect(2) が返す errno の一つで、Node.js・Python・Go・curl・psql など言語やツールを問わず同じ根本原因を指します。

TCP では、クライアントが SYN を送ったとき、その宛先ポートに LISTEN 中のソケットが無いと、相手のOSカーネルが RST（リセット）フラグを立てたセグメント（正確には RST/ACK）を即座に返します。クライアントのカーネルはこの RST を受けて connect() を ECONNREFUSED で失敗させます。ここで決定的に重要なのは即座に返るという挙動です。パケットが相手ホストのカーネルまで到達している証拠であり、名前解決も経路（ルーティング）も正常だと分かります。問題はもっと手前、そのポートで誰も聞いていないという一点に絞り込めます。

横にスクロール

よくある原因（複数を具体的に、頻度順）

1. サービスが起動していない（最頻）。 接続先のプロセス自体が動いていないケースです。デプロイ漏れ、クラッシュ後に再起動されていない、systemctl start を忘れた、コンテナが起動失敗している、などです。RST を返すのは相手ホストのカーネルなので、ホスト自体は生きているがアプリだけ死んでいる状況で典型的に起こります。

2. ポート番号が食い違っている。 クライアントが :3000 に繋ぎに行くのに、サーバーは :8080 で待っている、といった不一致です。環境変数の設定ミスや、開発と本番でポートが違うのに設定が追随していない場合に頻発します。

3. 待ち受けアドレスが 127.0.0.1（ループバック）に限定されている。 サーバーは起動しているのに、127.0.0.1（loopback）だけにバインドしていると、同一ホスト内からは繋がるのに他マシンやコンテナからは ECONNREFUSED になります。カーネルは loopback 宛のパケットを外部NICで受けないため、外から来た SYN に対しては「そのポートは開いていない」扱いとなり RST を返します。データベースやアプリサーバーで既定が 127.0.0.1 になっている製品は多く、リモート公開には 0.0.0.0（全アドレス）や特定NICへのバインド変更が要ります。

4. そもそも別のホストに繋ぎに行っている。 接続先IP／ホスト名の誤り、/etc/hosts の残骸、Docker/Kubernetes でサービス名の解決先を取り違えている、などです。到達先ホストは応答するがそのポートは使っていない、という形で Refused になります。

5. 起動直後の競合（レースコンディション）。 コンテナ群を同時起動したとき、依存先がまだ bind()／listen() を終える前に接続しに行くと一瞬だけ Refused が出ます。ヘルスチェックやリトライ、depends_on の待機条件が不足しているサインです。

診断の手順（切り分け方・見るべきログ/コマンド）

原則は「相手ホストで聞いているか」→「経路は通るか」→「アプリのログ」の順に外側から詰めることです。

手順1: 接続先ホスト上で LISTEN を確認する。 まず相手側で、狙ったポートが本当に待ち受けているかを見ます。ss が現在の標準（netstat の後継）です。

# -l LISTEN のみ / -t TCP / -n 名前解決しない / -p プロセス表示
ss -ltnp | grep ':3000'
# 出力例: LISTEN 0 511 127.0.0.1:3000 0.0.0.0:* users:(("node",pid=812,fd=20))

ここで確認すべきは2点です。第一にそのポートの行が存在するか（無ければ原因1のサービス未起動、または原因2のポート違い）。第二に Local Address が 0.0.0.0:3000 か 127.0.0.1:3000 かです。上の例は 127.0.0.1 なので、同一ホストからは繋がってもリモートからは Refused になります（原因3）。0.0.0.0 や [::] なら全インターフェースで待ち受けています。lsof でも同じ確認ができます。

lsof -iTCP:3000 -sTCP:LISTEN -P -n

手順2: クライアント側から到達性を測る。 次に接続元から、L3/L4 が通るかを確かめます。nc（netcat）か telnet が簡便です。

# -v 詳細 / -z データを送らず接続可否だけ / -w タイムアウト秒
nc -vz -w3 db.internal 5432
# 成功: Connection to db.internal 5432 port [tcp/postgresql] succeeded!
# 失敗: nc: connect to db.internal port 5432 (tcp) failed: Connection refused

ここでの結果が切り分けの核心です。Connection refused が即座に返るなら、パケットは相手ホストまで届いており、ポートが閉じている（アプリ側の問題）と確定します。逆に数秒沈黙してから timed out になるなら、経路上のファイアウォールがパケットを DROP している可能性が高く、原因はネットワーク側に移ります。curl でHTTPを試す場合も同じ errno がメッセージに出ます。

curl -v http://api.internal:8080/health
# curl: (7) Failed to connect to api.internal port 8080: Connection refused

手順3: アプリと接続文字列のログを読む。 LISTEN が存在するのに繋がらないなら、バインドアドレスの不一致か、接続先の指定ミスです。アプリ起動ログの Listening on ... 行のアドレス部を確認し（0.0.0.0 か localhost か）、クライアント側の接続文字列（ホスト名・ポート・DATABASE_URL 等の環境変数）が実際の待ち受けと一致しているかを突き合わせます。Docker では、コンテナ内の localhost はそのコンテナ自身を指すため、他コンテナへはサービス名で接続する必要があり、ここが典型的な取り違えポイントです。

解決と予防（対処と再発防止）

診断で切り分けた原因ごとに、対処は次のとおりです。

• サービス未起動（原因1）: プロセスを起動し、ss -ltnp で LISTEN を確認。クラッシュ再発は systemd の Restart=on-failure やオーケストレータの再起動ポリシーで自動復帰させる。
• ポート違い（原因2）: クライアントとサーバーの設定を単一の出所（環境変数・設定ファイル）に統一し、両者が同じ値を参照するようにする。ハードコードを排除する。
• 127.0.0.1 バインド（原因3）: リモート公開が必要なら待ち受けを 0.0.0.0（または該当NICのIP）に変更する。ただし無防備な全公開は避け、ファイアウォール・セキュリティグループでアクセス元を絞るのが前提。
• 接続先誤り（原因4）: ホスト名・IP・DNS／/etc/hosts を点検。コンテナ環境ではサービス名解決を使う。
• 起動レース（原因5）: 接続側にリトライ（指数バックオフ）を実装し、依存先のヘルスチェック成功を待ってからトラフィックを流す。depends_on の condition: service_healthy 等を使う。

TCP のハンドシェイクと RST の意味、ポート・ソケットの動作はネットワークを、bind()／listen() とループバックの扱いはOSを、バインド公開に伴うアクセス制御の設計はセキュリティを参照してください。