ETIMEDOUT（Connection timed out）

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

ETIMEDOUT（多くのライブラリで Error: connect ETIMEDOUT や Connection timed out）は、接続の相手が制限時間内に一切応答しなかったことを示すエラーです。TCP では接続開始時にクライアントが SYN パケットを送り、相手の SYN-ACK を待ちます。この応答が返らないと OS はカーネルのタイマーに従って SYN を数回再送し、それでも無応答なら接続試行を打ち切って ETIMEDOUT を返します。

決定的なのは ECONNREFUSED との違いです。両者は「つながらない」点では同じでも、相手の反応がまるで逆です。

つまり ECONNREFUSED は「ホストは生きていて、はっきり断られた」、ETIMEDOUT は「返事すら来ない」。前者はポート番号やサービス起動状態を、後者は経路・中間装置・相手の飽和を疑うのが出発点です。

横にスクロール

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

1. ファイアウォール／セキュリティグループでのサイレントドロップ（最頻）。拒否には「REJECT（RSTやICMPを返す）」と「DROP（黙って捨てる）」があり、クラウドのセキュリティグループや多くの企業FWは既定で DROP します。DROP されるとクライアントには何も返らないため、必然的に ETIMEDOUT になります。ポートの開放漏れ、送信元IP制限、片方向だけ開いている（戻りが塞がれている）ケースが典型です。

2. 経路不通（ルーティング／到達性の問題）。宛先ホストがダウンしている、ルートテーブルの設定漏れ、NAT/VPN 経由の非対称経路、オンプレとクラウド間の経路広告漏れなどで、SYN が相手に届かない、または戻りが返らない状態です。

3. 相手サーバーの過負荷（accept backlog 溢れ）。相手プロセスは生きていても、accept() キュー（net.core.somaxconn と listen() の backlog）が満杯だと、確立途中の接続が溢れて破棄され、クライアントからは応答なしに見えます。負荷スパイク時やスレッドプール枯渇時に散発的な ETIMEDOUT として現れます。

4. DNS 解決の遅延・タイムアウト。名前解決が遅い、または DNS サーバーが無応答だと、TCP 接続に到達する前にアプリの総タイムアウトを超えます。厳密には接続タイムアウトと別物ですが、症状（固まってから失敗）が似ているため混同されがちです。Node.js では getaddrinfo ETIMEDOUT として区別できます。

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

手順1: どの段階で失敗しているかを curl -v で確定する。 ログの1行がすべてを教えます。

curl -v --connect-timeout 5 https://api.example.com/
# "Trying 203.0.113.10:443..." で止まる → TCP接続そのものが不成立（本記事の対象）
# "Connected to ..." の後で止まる → 接続は成立、TLS/アプリ層の問題
# 名前解決で止まる → DNS の問題

手順2: 相手ポートへの到達性を直接叩く。 ping は ICMP なので通っても TCP ポートが塞がれていることは多々あります。目的のポートへ届くかを見ます。

# TCPレベルでポートの開放を確認（ncが無ければ /dev/tcp）
nc -vz -w 5 api.example.com 443
# 即 refused → ECONNREFUSED（サービス未起動）
# 5秒無応答で失敗 → ドロップ（FW/経路）
timeout 5 bash -c '</dev/tcp/api.example.com/443' && echo OPEN || echo "DROP/CLOSED"

手順3: 経路のどこで消えるかを追う。 traceroute（Windows は tracert）で応答が途切れるホップを見ます。特定ホップ以降がすべて * * * なら、その先で経路断かフィルタが起きています。

traceroute -n -w 2 api.example.com     # UDP。途中から * ばかりなら経路/FW を疑う
traceroute -T -p 443 -n api.example.com # 実ポートへTCPで。ICMP遮断環境で有効

手順4: パケットドロップを直接観測する。 これが最終確定です。SYN が出ているのに SYN-ACK が返らず、SYN の再送だけが並ぶなら、パケットが往路か復路で捨てられている動かぬ証拠です。

sudo tcpdump -n -i any "host api.example.com and tcp port 443"
# 送信側に SYN が複数（再送）、相手からの SYN-ACK が皆無 → ドロップ確定
# ss -tan で SYN-SENT のまま張り付く接続も傍証になる

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

到達性を直す（根本対処）。 ドロップが原因なら、FW／セキュリティグループで対象ポートを開け、戻り方向（ステートフルなら通常は自動、そうでなければエフェメラルポート範囲）も確認します。経路不通ならルートテーブル、VPN/NAT の設定、DNS レコードを是正します。過負荷が原因なら net.core.somaxconn と listen() backlog を引き上げ、アプリの並行数やコネクションプール上限、上流のスケールを見直します。

タイムアウトを明示的に設計する（再発防止の要）。 多くのクライアントは既定のOSタイムアウトに任せており、失敗確定まで数十秒スレッドを占有します。これがスレッドプールを食い潰し、障害を連鎖させます。接続タイムアウトと読み取りタイムアウトは必ず分けて短く設定してください。

// 接続は速く諦め、読み取りは用途に応じて別枠にする
const res = await fetch(url, {
  signal: AbortSignal.timeout(3000), // 全体の上限。接続で固まっても即諦める
});
// libcurl系: --connect-timeout（接続）と --max-time（全体）を別々に指定する

再試行はバックオフとサーキットブレーカーで守る。 ETIMEDOUT は一過性のことも多いため指数バックオフ＋ジッターでの再試行が有効ですが、相手が飽和しているときに素朴に再試行すると傷口を広げます。連続失敗でサーキットブレーカーを開き、一定時間フェイルファストへ切り替えるのが定石です。TCP レベルでの早期検知には TCP_USER_TIMEOUT や Keepalive も併用できます。

TCP のハンドシェイクと再送の内部動作はネットワーク、FW・セキュリティグループの拒否ポリシー設計はセキュリティ、タイムアウトとリトライを組み込んだ耐障害設計はDevOpsを参照してください。