トラブルシューティング

Kisenon はアルファ段階です。ここでは、最も遭遇しやすい失敗モードと、それぞれを乗り越える方法を 紹介します。

エンドポイントが Pending でスタックする

症状： 作成時にエンドポイントが数秒以上 Pending のままになる。コンソールはエラーを表示せ ず、CLI も同じ状態を表示する。

考えられる原因： コンピュートポッドをスケジュールできない。最も一般的な理由は、クラスタの 圧迫（要求された CPU またはメモリが空いているノードがない）か、古いイメージプル資格情報です。 どちらもオペレーター側の問題です。

対処：

1. 60 秒待ちます。一時的な圧迫は、別のエンドポイントがサスペンドすると通常解消します。
2. 解消しない場合は、エンドポイントを削除して再作成します。コントロールプレーンは別のノードで スケジューリングを再試行します。
3. 再作成も Pending に着地する場合、クラスタが不調です。エンドポイント id と実時刻を添えて、 GitHub トラッカー に報告を立ててください。

最初の接続での FATAL: endpoint unavailable

症状： 新しく作成されたエンドポイントへの一番最初の接続、または長いアイドルの後に、psql が FATAL: endpoint unavailable を返す。

考えられる原因： コールドスタートのレース。エンドポイントの状態は Stopped で、あなたの パケットがそれを起動しましたが、クライアントが諦めた時点でも Postgres はまだブランチの HEAD まで WAL をリプレイしています。

対処： 接続を再試行してください。コールドスタートは通常 300〜500 ミリ秒で完了しますが、新しく 作成されたプロジェクトの一番最初の起動、または 24 時間以上のアイドルの後は、pageserver のページ キャッシュが温まる間、10〜30 秒かかる場合があります。少なくとも 1 回のリトライを許せば、ほとんど のドライバはこれを許容します。生の psql はデフォルトでは再試行しません。

# psql with one explicit retry
for i in 1 2; do psql "$URI" -c '\q' && break; sleep 5; done

30 秒経ってもエンドポイントがまだ利用できない場合、ポッド自体が失敗している可能性があります。 コンソールで状態を確認し、上記の Pending のガイダンスを参照してください。

keon connection-string が branch_not_found を返す

症状：

$ keon connection-string my-feature --project prj_abc...
Error: branch_not_found: my-feature

…しかしブランチはコンソールに存在する。

考えられる原因： その名前が、対象にしたプロジェクト内のブランチに一致していません — 通常は タイプミスか、--project が間違っています。CLI はブランチを id または名前で解決し、位置引数とし て渡しても --branch 経由で渡しても同じなので、実在する名前ならどちらでも解決します。

対処： ブランチ名とプロジェクトを確認してください。

keon branches list --project prj_abc...
keon connection-string my-feature --project prj_abc...

サインインが access_denied を返す

症状： Google または GitHub の OAuth は完了するが、コンソールが access_denied を挙げる エラーページにリダイレクトする。

考えられる原因： アルファ期間中、サインインはメール許可リストでゲートされています。あなたの アドレスがオンボードされていない場合、サインインコールバックは原則としてそれを拒否します。

対処： アルファアクセス で申請してください。あなたのアドレスが許可リストに 追加されると、次回の試行でサインインは正常に完了します。

コンソールセッションがセッション中に失効する

症状： コンソールはしばらく動作するが、突然すべての API 呼び出しで 401 を返すようになり、 サインアウトして再度サインインするまで続く。

考えられる原因： cp 署名済み JWT が失効し、その更新ウィンドウが過ぎました。コンソールは短命 の JWT（約 15 分）を発行し、あなたがアクティブな間は /v1/auth/refresh に対してバックグラウンド で更新します。更新ウィンドウはサインインから 12 時間に固定されています。アクティブなセッションは 無期限に更新されますが、そのウィンドウを過ぎて放置されたタブはもう更新できません。

対処： サインアウトして再度サインインしてください。ヘッドレスまたは長時間実行の自動化には、 ブラウザセッションの代わりに nsk_ API キーを使ってください。API キーは失効せず、明示的に取り 消されます。認証 を参照してください。

バグの報告先

ここで扱われていないことについては：

• 製品のバグと機能リクエスト： GitHub トラッカー。
• セキュリティ脆弱性：セキュリティ — 公開トラッカーには決して報告しないでくだ さい。

具体的な再現手順、影響を受ける id（プロジェクト、ブランチ、エンドポイント）、実時刻のタイムスタ ンプがあると、往復が劇的に短くなります。