Posts

結論 connection refused は PostgreSQL が生成した文言ではありません。接続先の OS が接続要求を拒んだときの ECONNREFUSED を、libpq が strerror() の結果としてそのまま転記したものです。実装では、接続に失敗した箇所で SOCK_STRERROR(errorno, ...) の結果を先頭に置き、その後ろに助言の1行を足しています。 この由来から、確認すべき範囲がほぼ確定します。要求は指定した相手とポートまで届いており、そこで待ち受けている相手がいなかったという意味です。したがって、パスワード、pg_hba.conf、ロール、データベース名は一切関係ありません。これらの問題であれば、接続自体は成立したうえで PostgreSQL 側の FATAL が返ります。 見るべきは3つです。サーバーが動いているか、待ち受けている住所に自分が届いているか、ポート番号が合っているかです。 エラーが発生する処理段階 クライアントが接続を確立するまでには段階があります。connection refused は最初の段階、つまり connect() の呼び出しで止まっています。 第一段階は接続先の決定です。libpq は host から名前を引き、hostaddr があればそちらを使います。第二段階が実際の接続で、ここで拒否されると connection refused になります。第三段階が起動時のやり取りで、データベース名と利用者名を送ります。第四段階が認証で、pg_hba.conf の照合とパスワードの確認が行われます。 第二段階で止まっているということは、PostgreSQL のプロセスがこの要求を一度も見ていないということです。サーバーのログにも何も残りません。ログを探しても記録が無いのは異常ではなく、この段階で止まっている証拠です。 最初に確認すること まず、どの相手のどのポートに対して拒否されたのかを、エラー文からそのまま読み取ります。 psql: error: connection to server at "localhost" (::1), port 5432 failed: Connection refused Is the server running on that host and accepting TCP/IP connections? 括弧の中は、名前を引いた結果の実際の住所です。ここが ::1 になっているのに待ち受けが IPv4 だけ、という食い違いはよく起きます。localhost は環境によって IPv6 を先に返すためです。 ...

結論 password authentication failed for user "app" は、原因を意図的に伏せた文言です。実装では、pg_hba.conf の照合方式が password・md5・scram-sha-256 のいずれかであれば、失敗の中身にかかわらずこの1文が返ります。 伏せる理由は実装のコメントに書かれています。パスワードの取得に失敗しても、利用者が存在しないことをクライアントに悟らせないために、認証の手順を最後まで進めるという作りです。したがって、存在しないロール名で接続しても、パスワードを間違えた場合とまったく同じ文言が返ります。 本当の理由は errdetail_log() で出力されており、これはサーバーのログにだけ書かれます。クライアントには届きません。しかも、この詳細には照合に使われた pg_hba.conf の経路と行番号、その行の原文まで含まれています。 つまり最初にすべきことはパスワードの再入力ではなく、サーバーのログを開くことです。 エラーが発生する処理段階 このエラーは接続が成立したあとに出ます。手前の段階はすべて通っています。 まず TCP または Unix ドメインソケットの接続が確立します。ここで拒まれれば connection refused になり、この文言は出ません。次に起動時のやり取りで、データベース名と利用者名がサーバーへ送られます。 続いて pg_hba.conf の照合です。上から順に、接続の種類・データベース・利用者・接続元を見て、最初に一致した行が採用されます。一致する行が1つも無ければ no pg_hba.conf entry for host になります。 一致した行の方式がパスワード系であれば、ここで確認が行われます。失敗するとこの文言が返ります。データベースの存在確認や接続権限の確認は、さらに後の段階です。 最初に確認すること クライアント側の表示には、状態コード以上の情報はありません。 psql: error: connection to server at "db.internal" (10.0.1.5), port 5432 failed: FATAL: password authentication failed for user "app" サーバーのログを開くと、同じ時刻に DETAIL が並んで出ています。 sudo tail -n 50 /var/log/postgresql/postgresql-16-main.log 出力はこの形になります。 FATAL: password authentication failed for user "app" DETAIL: Password does not match for user "app". Connection matched file "/etc/postgresql/16/main/pg_hba.conf" line 96: "host all all 10.0.1.0/24 scram-sha-256" 1行目の DETAIL が本当の理由です。実装で定義されている文言は6種類で、Role "app" does not exist.、User "app" has no password assigned.、User "app" has an expired password.、User "app" has a password that cannot be used with MD5 authentication.、Password does not match for user "app".、Password of user "app" is in unrecognized format. です。どれが出ているかで、次に見る場所が確定します。 ...

冒頭まとめ ERROR: failed to solve: を原因名として検索しているなら、探す場所がずれています。この一行は1つの部品が出した文言ではなく、3か所が順に書き足した結果です。 先頭の ERROR: を付けるのは buildx の入口部分です（cmd/buildx/main.go）。続く failed to solve は、BuildKit のクライアントがビルドサーバーから受け取ったエラーを包む語です（client/solve.go）。コロンより後ろが、失敗した部品の言い分です。 読むのはコロンの直後です。 process "..." なら実行を担う部分、failed to resolve source metadata for ならイメージ参照の解決、failed to compute cache key なら solver、failed to prepare ならキャッシュ管理が書き手です。failed commit on ref に至っては BuildKit ですらなく、同梱の containerd が出しています。 もう1つの読みどころが ------ Dockerfile:3 ------ の囲みです。エラーに Dockerfile 上の位置情報が付いているときだけ出ます（solver/errdefs/source.go）。囲みの有無で、疑う対象が Dockerfile の中身か外側かに分かれます。 エラーの概要 BuildKit のビルドは、Dockerfile を内部表現へ変換する段、イメージ参照を解決する段、コマンドを実行する段、書き出す段の順に進みます。failed to solve は全体を包む外枠で、どの段で止まっても先頭は同じです。区別できるのは後ろだけです。 型1：ステップ見出しと Dockerfile の囲みを伴う > [2/2] RUN apk add --no-cache bash: ... exited with error 127 2 errors ------ Dockerfile:3 -------------------- 1 | FROM alpine:3.23 2 | 3 | >>> RUN apk add --no-cache bash 4 | -------------------- ERROR: failed to build: failed to solve: process "/dev/.buildkit_qemu_emulator /bin/sh -c apk add --no-cache bash" did not complete successfully: exit code: 2 > [2/2] がステップ番号、>>> の行が失敗した命令、区切りの手前の exited with error 127 がコマンド自身の出力です。末尾の exit code: 2 は結果であり、理由ではありません。 ...

冒頭まとめ An argument named "..." is not expected here. を見たとき、多くの人は指し示された行の書き方が間違っていると考えます。しかし、この文言は設定ファイルのボディをあらかじめ決められたスキーマと照合した結果として出るものです。エラーが指すのは「引数名を書いた位置」であり、その引数を受け付けない側の情報は行番号のどこにも現れません。 したがって、直すべき対象は行ではなく、期待される引数の集合を決めている側です。これは大きく3系統に分かれます。resource / data / provider ブロックなら、いま初期化済みの provider が持つスキーマ。module ブロックなら、子 module 側に書かれた variable 宣言。terraform や lifecycle のような固定ブロックなら Terraform 本体です。 この区別を飛ばすと、典型的な失敗に入ります。module 呼び出しで拒否されたのに、呼び出し側（ルート）の variables.tf へ同名の変数を追加してしまう例が繰り返し報告されています。宣言が必要なのは子 module の側なので、これでは通りません。また、公式ドキュメントどおりに書いたのに拒否されるという報告も多く、この場合はドキュメントの版と実際にインストールされている provider の版がずれています。 判断の起点は、エラー出力の on ... line N, in ... の行です。ファイルパスと、その後ろのブロック種別を読めば、どの系統が拒否したかがほぼ決まります。末尾に Did you mean が付いているかどうかも、そのまま分岐材料になります。 エラーの概要 エラーは次の形で出ます。まず、module 呼び出しで未宣言の入力を渡した場合です。 Error: Unsupported argument on main.tf line 25, in module "sh": 25: num = 4 An argument named "num" is not expected here. 読むべきは3箇所です。1つ目は on に続くファイルパス。2つ目は in に続くブロック種別と名前。ここが in module "sh" なので、期待集合を決めているのは子 module の variable 宣言であり、provider は無関係です。3つ目は最後の行のサフィックス。この例では何も付いていません。 ...

冒頭まとめ manifest unknown は、レジストリとの通信自体は成立しているのに、指定した image reference（タグまたはダイジェスト）に対応する manifest がそのリポジトリで解決できなかったときに出るエラーです。OCI Distribution Specification では、リポジトリに blob または manifest が見つからない場合の応答は 404 Not Found と定められており、この系統のエラーは「サーバーが壊れている」ではなく「参照先が存在するか」を疑うところから始めます（OCI Distribution Specification）。 調査は次の3点を順に確認するのが最短です。 指定したタグまたはダイジェストが、そのリポジトリに実在するか image reference の各要素（レジストリホスト、名前空間、リポジトリ名、タグ、プラットフォーム）が意図したものになっているか 直前の build・tag・push、マルチアーキテクチャの manifest 公開が本当に完了しているか エラーの概要 manifest unknown は、レジストリが「そのリポジトリに、要求された manifest がない」と応答している状態です。名前解決や TLS の失敗とは違い、リクエストはレジストリまで届いています。認証エラーとも異なり、レジストリはリクエストを受け付けたうえで「該当なし」を返しています。 近いエラーとの違いを整理すると、次のように分類できます。 出力の傾向 意味するもの 最初に見る場所 manifest unknown（manifest が見つからない） 参照先のタグ・ダイジェストが存在しない image reference とタグ一覧 denied / unauthorized などの権限系の文言 認証・認可が足りない、または対象が非公開 ログイン状態とアクセス権 接続タイムアウト、名前解決失敗、証明書エラー レジストリまで到達できていない ネットワーク、プロキシ、TLS 設定 500・502・503・504 レジストリ側の障害 レジストリの稼働状況 なお、非公開リポジトリに対して存在を隠すために「見つからない」相当の応答を返すレジストリもあります。権限系と参照先不在の切り分けで迷う場合は、対象レジストリの公式ドキュメントで応答の仕様を確認してください。 本記事が扱う範囲は、docker pull や docker push の時点で発生する、レジストリ上の manifest 解決失敗です。認証・認可エラー、レジストリへの到達性そのものの問題、および Kubernetes の Pod sandbox 作成段階のイベント（FailedCreatePodSandbox など）は、発生する層が異なるため本記事の対象外とします。 ...

冒頭まとめ FailedCreatePodSandbox は、kubelet が Pod の sandbox（ネットワーク名前空間や pause コンテナといった、コンテナ起動前の土台）を作成できなかったときに記録される警告イベントです。Pod は ContainerCreating のまま止まり、kubelet はリトライを繰り返します。 原因はほぼ次の3方向に分かれます。 CNI プラグインまたは CNI 設定の不整合で、Pod のネットワーク設定（IP 割り当てを含む）に失敗している container runtime が sandbox image（pause image）を取得・起動できず、sandbox コンテナを作れない ノード側の状態（ディスク、iptables/sysctl、カーネルモジュール、runtime プロセス）が壊れている 調査の出発点は「イベント本文の desc = 以降に書かれた、container runtime から返った実メッセージ」です。ここに cni / network / image / no space left on device のどの語が出ているかで、上の1〜3のどれを追うべきかがほぼ決まります。次に「1ノードだけの問題か、クラスタ全体か」を確認すると、ノード修復かクラスタ設定修正かの判断が付きます。 エラーの概要 これは HTTP ステータスではなく kubelet のイベント理由です FailedCreatePodSandbox はエラーコードではなく、kubelet が Pod に対して発行する Event の reason です。kubectl describe pod の Events 欄や kubectl get events に現れます。 実際にクラスタ上で出力される文字列は FailedCreatePodSandBox（Box の B が大文字） です。ログやイベントを検索するときは大文字小文字を区別しない検索（grep -i）を使うと取りこぼしが減ります。 ...

冒頭まとめ Init:CrashLoopBackOff は、Pod の init container が失敗して終了し、kubelet による再起動が繰り返されてバックオフ待ちに入っている状態を示します。Kubernetes 公式ドキュメントでは、init container は必ず完了まで実行され、次の init container が始まる前に成功して終了する必要があり、init container が失敗した場合は kubelet が成功するまでその init container を繰り返し再起動すると説明されています。つまりこのエラーが出ている間、通常（アプリ）コンテナは一度も起動していません。 調査の出発点は次の 2 つです。 kubectl describe pod <pod-name> と status.initContainerStatuses で、どの init container が止まっているかを特定する。 kubectl logs <pod-name> -c <init-container> --previous で、直前に終了したインスタンスの終了理由を確認する。 本体コンテナの CrashLoopBackOff と混同すると調査対象がずれます。Init: の接頭辞が付いている間は、修正対象は init container 側です。 エラーの概要 Init:CrashLoopBackOff は Pod の STATUS 列に表示される文字列で、Pod の初期化フェーズで失敗が繰り返されていることを表します。 公式ドキュメントで確認できる init container の性質は次のとおりです。 init container は通常のコンテナとほぼ同じですが、常に完了まで実行される点が異なります。各 init container は、次の init container が起動する前に成功して完了しなければなりません。 init container が失敗した場合、kubelet はそれが成功するまで繰り返し再起動します。ただし Pod の restartPolicy が Never で、起動中に init container が失敗した場合は、Kubernetes は Pod 全体を失敗として扱います。 Pod の STATUS は初期化の進み方を示します。Debug Init Containers では、たとえば Init:1/2 は 2 つある init container のうち 1 つが成功して完了したことを示すと説明されています。 近い表示との違いを整理します。 ...

冒頭まとめ RunContainerError は、HTTPステータスコードではなく、Pod内のコンテナ状態に出る waiting.reason です。Podはノードに割り当てられ、Pod sandboxも作られた後、kubeletがcontainer runtimeへコンテナ起動を依頼した段階で失敗しています。 State: Waiting Reason: RunContainerError Message: <container runtime が返した実メッセージ> ここで重要なのは、RunContainerError という文字だけでは原因が決まらないことです。原因は隣にある Message、直近のEvents、そして同じノード上の他Podの状態から切り分けます。 まず次の4つを分けてください。 表示されているreasonが本当に RunContainerError なのか。 messageがワークロード設定の問題を示しているのか。 volume、権限、セキュリティ設定など、Pod定義とノード条件の組み合わせで失敗しているのか。 containerd、CRI-O、runc、cgroup、ディスクなど、ノード側runtimeの問題なのか。 kubectl logs が空でも不思議ではありません。プロセスがまだ開始できていないため、アプリケーションログへ到達しないことがあります。最初に読むべきなのは、アプリログではなく kubectl describe pod のState、Message、Eventsです。 エラーの概要 KubernetesのPod起動は、ざっくり次の段階に分けられます。 Scheduling ↓ Image pull ↓ Pod sandbox 作成 ↓ Container 作成 ↓ Container 起動 ↓ Application 実行 RunContainerError は、このうち Container作成または起動 の近辺で止まっている状態です。kubeletの実装では、RunContainerError はコンテナ起動時の失敗を表すエラーとして定義されています（sync_result.go）。 したがって、RunContainerError を見た時点で、少なくとも次の切り分けが必要です。 kubectl get pod <Pod名> -n <名前空間> \ -o jsonpath='{range .status.containerStatuses[*]}{.name}{"\t"}{.state.waiting.reason}{"\t"}{.state.waiting.message}{"\n"}{end}' initコンテナで止まっている場合は、見る場所が変わります。 ...

冒頭まとめ ContainerCreating は、根本原因を示すエラー名ではありません。kubectl get pods が、Kubernetesでコンテナをまだ開始できていない状態を要約して表示したものです。 NAME READY STATUS RESTARTS AGE app-7f6f8d9c75-2kq8m 0/1 ContainerCreating 0 8m API上では、Podの段階は Pending、コンテナの状態は Waiting、その理由が ContainerCreating になっていることがあります。 Status: Pending State: Waiting Reason: ContainerCreating Kubernetes公式のPodライフサイクルは、kubectl の STATUS 欄をPodの phase と混同しないよう明記しています。ContainerCreating を見ただけでは、ボリューム、イメージ取得、Podの通信環境、コンテナ実行基盤のどこで止まったかは決まりません。 そこで、次に kubectl describe pod の Events を読みます。 Warning FailedMount 2m (x8 over 7m) kubelet MountVolume.SetUp failed for volume "config" : configmap "app-config" not found この場合、ContainerCreating は現在の待機状態、FailedMount はボリュームの準備に失敗した試行の記録です。直す対象を示しているのは、FailedMount より後ろの文です。 configmap "app-config" not found rpc error: code = ... desc = ... driver name ... not found in the list of registered CSI drivers mount failed: exit status 32 volume is already exclusively attached to one node つまり、ContainerCreating を直接直すのではなく、最新イベントの具体的な失敗を直します。FailedMount があるなら、最初に対象ボリューム名をPodの volumes と対応させ、参照先がSecret、ConfigMap、PVC、CSIのどれかを確定します。 ...

冒頭まとめ Cannot connect to the Docker daemon は、Dockerの操作役である docker コマンドが、実行役の dockerd と通信できなかったという意味です。 最初に押さえるべきは、このエラーだけでは daemon が停止しているとは限らないことです。Docker公式のトラブルシューティングにも、daemon が動いていない場合だけでなく、クライアントが別の接続先を向いていて、その接続先へ到達できない場合があると書かれています。 一方、次の permission denied は一段具体的です。 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: dial unix /var/run/docker.sock: connect: permission denied これは、daemon の停止を確認する前に、利用者がソケットへ接続する権限を疑うべき文言です。Linuxでは通常、/var/run/docker.sock を通してDocker APIを呼びます。ソケットが root:docker の所有で、現在の利用者が有効な docker グループに入っていなければ、接続の時点で拒否されます。 2つは同じ接続失敗の系統ですが、同じ原因ではありません。読むべき部分は末尾です。 connect: permission denied → ソケットへの権限を確認する connect: no such file ... → 接続先またはdaemonの起動を確認する connection refused → 接続先に受け手がいるかを確認する つまり、Is the docker daemon running? という問いをそのまま答えにしないことが重要です。まずクライアントがどこへ接続しようとしているかを確定し、次にその接続先でdaemonが動いているか、最後に現在の利用者が接続できるかを見ます。 エラーの概要 Docker Engine は、docker というクライアント、dockerd という常駐処理、両者を結ぶAPIから成ります。docker ps や docker compose up を実行すると、クライアントが選択中の接続先へAPI要求を送ります。 ...