eve-troubleshooting

Eve のトラブルシューティング

CLI を優先して診断してください。クラスターにアクセスできるとは限りません。

クイックトリアージチェックリスト

eve system health
eve auth status
eve job list --phase active

よくある問題と解決方法

認証に失敗する、または「Not authenticated」と表示される

eve auth logout
eve auth login
eve auth status

SSH キーがない場合は、管理者に登録を依頼するか、CLI のプロンプトに従って GitHub から取得してください。

シークレットが見つからない／補間エラー

eve secrets list --project proj_xxx
eve secrets set MISSING_KEY "value" --project proj_xxx

ローカルでの補間に .eve/dev-secrets.yaml が存在することを確認してください。

デプロイジョブが失敗する

eve job follow <job-id>
eve job diagnose <job-id>
eve job result <job-id>
eve env diagnose <project> <env>     # structured DeployFailure + cluster snapshot

レジストリ認証エラー、シークレットの不足、またはヘルスチェックの失敗がないか確認してください。

eve env diagnose は、型付きの last_deploy_failure（kind、service、pod、namespace、message）と稼働中の K8s の状態を表示します。まず失敗の kind を確認してください。CLI は実際の原因を単なる HTTP request failed にまとめることはなくなりました。diagnose の manifest_hash と最新の同期結果を比較し、適用済みリリースとのずれがないか確認してください。

Sentinel の Slack アラート

プラットフォームの sentinel から Slack に通知が届いた場合、環境の状態が悪化しています。アラートの文面だけで対処せず、そこからプロジェクトと環境を特定し、eve env diagnose <project> <env> で再確認してください。環境が正常であれば、一時的な問題が自動復旧したということです。正常でなければ、上記の標準的なデプロイ失敗のトリアージに従ってください。

マジックリンクまたは招待メールが届かない

通常、事前チェックで SES の設定ミスが検出されますが、受信者がメールを受け取っていないと主張する場合は、次の手順を実行してください。

eve admin email bounces list --recipient [email protected] --limit 20
eve admin email bounces list --event-type Bounce
eve admin email bounces list --event-type Complaint

email_delivery_events テーブルが正となる情報源です。Bounce／Complaint／Reject の行から、SES が通知なしに配信を停止した理由を確認できます。行がまったくない場合は送信自体が行われていません。プロジェクトの x-eve.branding にある返信先／サポート用メールアドレスと、x-eve.auth ポリシーを再確認してください。

マジックリンクを初回クリックしたときに「Already Used」と表示される

メールセキュリティスキャナー（Defender SafeLinks、Mimecast、Proofpoint、Barracuda、IronPort）が URL を事前取得し、1 回限りの OTP を消費することがあります。現在、プラットフォームではすべてのアクションリンクを SSO のインタースティシャル画面でラップし、明示的なクリックを要求するため、事前取得でトークンが消費されることはありません。それでも「already used」と表示される場合は、次のいずれかです。

• ラップの有効期限が切れています（TTL は 1 時間）。新しいマジックリンクをリクエストしてもらってください。
• 実際に 2 回クリックしています。2 回目のクリックでは、消費済みのラップが使用されます。
• テレメトリー：magic_link_wraps に get_count > 1 の行があるのは、保護されたメールボックスでは想定どおりです。確認するのは consumed_at のみです。

マジックリンクまたは招待のリンク先が汎用 SSO ページになる

リダイレクト許可リストでアプリのカスタムドメインのオリジンが拒否されたため、SSO がクラスターのランディングページにフォールバックしました。プロジェクトの x-eve.auth.allowed_redirect_origins（または登録済みの custom_domains 行）にアプリのオリジンが含まれていることを確認してください。指定するのはオリジンのみ（scheme://host[:port]）で、ローカル環境以外では https を使用します。その後、再同期してください。

eve project sync
eve project auth-context <project_id>     # shows the resolved allowlist

パス、クエリ、フラグメント、userinfo は同期時に拒否されるため、マニフェストに https://app.example.com/callback などが誤って含まれている場合は、その時点で検出されます。

カスタムドメインのアプリで /session が 401 になる

ブラウザーはクロスサイトリクエストで SameSite=Lax の Cookie を除外するため、カスタムドメインのアプリから sso.<cluster> にアクセスすると、eve_sso_rt が送信されず 401 になります。SSO ブローカーは現在、EVE_SSO_SECURE_COOKIES=true の場合に SameSite=None; Secure を設定します。ブローカーのログで確認してください。

[eve-sso] Secure cookies: true (SameSite=none)

ブラウザーの開発者ツールで、.<EVE_DEFAULT_DOMAIN> の eve_sso_rt Cookie に SameSite=None; Secure; HttpOnly が表示されていることを確認してください。Lax と表示される場合、ブローカーはローカル HTTP モードで動作しています。EVE_SSO_SECURE_COOKIES=true を設定して再デプロイしてください。ローカル k3d の *.lvh.me では、同じ親サイトであるため、意図的に Lax が維持されます。

アップグレード後にドメイン登録マニフェストが拒否される

v1 の形式（domains: [string] とブロックレベルの target_org）は 2026-05-12 以降受け付けられなくなり、マニフェストの同期時に検出されると拒否されます。v2 に移行してください。

x-eve:
  auth:
    org_access:
      domain_signup:
        enabled: true
        domains:
          - { domain: acme.com, target_org: org_acme, role: member }
          - { domain: partner.example, target_org: org_partner }

各ルールで独自の target_org を宣言する必要があり、各 target_org はプロジェクトの allowed_orgs にすでに含まれている必要があります。フリーメールのドメイン（free-mail.example、outlook.com など）では整合性に関する警告が出ますが、拒否はされません。これらを宣言するのは、ほとんどの場合誤りです。v2 の形式の詳細は、references/manifest.md と docs/system/auth.md#domain-based-signup を参照してください。

ワークフローステップで「リソースへのアクセスが拒否されました」と表示される

ワークフローステップのジョブには、ワークフローおよびステップレベルの scope ブロックから導出された token_scope クレームが付与されるようになりました（API から指定された scope がある場合は、その内容と積集合を取ります）。組織のファイルシステムパス、環境 DB テーブル、または Cloud FS マウントでステップが denied になる場合、原因はスコープにあると考えられます。

eve job show <job-id> --json | jq '.token_scope'

クレームをマニフェストのワークフロー／ステップの scope と比較してください。ステップスコープはワークフロースコープとの積集合になるため、範囲を狭めることしかできず、広げることはできません。ワークフローで許可されていないパスがステップに必要な場合は、ワークフローの scope を広げるか、削除してください。リクエストで指定する scope には jobs:harness_override 権限が必要です。現時点では --scope-* CLI フラグはありません。

カスタムドメインの問題

eve domain verify <hostname>     # DNS check + cert state + next steps
eve domain status <hostname>     # which env owns it
eve domain list --env <env>      # everything bound to this env

よくある原因：

• DNS が解決されていない：verify には想定されるターゲットと dns_result.verified: false が表示されます。再度デプロイする前に CNAME/A レコードを修正してください。
• 証明書の発行待ち：cert-manager の HTTP-01 チャレンジが進行中です。1 分ほど待ってから verify を再実行してください。
• 先着優先の競合：別の環境がすでにホスト名を確保しています。eve domain transfer <host> --to <env> を実行して再デプロイするか、environments.<env>.overrides でドメインを環境ごとに設定してください。

レジストリへのプッシュが UNAUTHORIZED で失敗する

ビルドジョブでイメージのプッシュ時に UNAUTHORIZED: authentication required が発生する場合：

1. シークレットが設定されていることを確認します：eve secrets list --project proj_xxx
2. カスタム BYO レジストリを使用している場合、認証情報が registry.host に対応していることを確認します
3. マニフェストの imagePull メタデータが正しいことを確認します
4. Dockerfile に OCI ソースラベルを追加します：LABEL org.opencontainers.image.source="https://github.com/ORG/REPO"

一部のレジストリでは、リポジトリにリンクされたパッケージメタデータ、またはワークスペースレベルの認証設定の整合性が必要です。

ビルドの失敗

症状

• パイプラインがビルドステップで失敗する
• eve build diagnose の実行ステータスが failed と表示される

トリアージ

eve build list --project <id>          # Find recent builds
eve build diagnose <build_id>          # Full state dump
eve build logs <build_id>              # Raw build output

よくある原因

レジストリの認証：

• カスタムレジストリモードを使用している場合、REGISTRY_USERNAME と REGISTRY_PASSWORD のシークレット、またはプロバイダーに相当するレジストリ認証情報が設定されていることを確認します。マネージドレジストリ（registry: "eve"）では、通常この手順は不要です。
• 認証情報で、設定されたレジストリアカウントと名前空間にアクセスできることを確認します
• 次を確認します：eve secrets list --project <id>

Dockerfile の問題：

• マニフェスト内で、Dockerfile を含むディレクトリを指す build.context をサービスに設定する必要があります
• Dockerfile のパスは既定で <context>/Dockerfile です
• BuildKit ではマルチステージビルドが動作しますが、Kaniko では失敗する場合があります

ワークスペース／クローンのエラー：

• ビルドには、正しい git SHA のワークスペースが必要です
• ワークスペースの準備エラーについては eve build diagnose を確認します

イメージのプッシュ失敗：

• OCI ラベルを追加すると、パッケージをリポジトリにリンクできます：Dockerfile に LABEL org.opencontainers.image.source="https://github.com/OWNER/REPO" を追加します
• BYO／カスタムレジストリを使用している場合、レジストリホストと認証情報がマニフェストの registry.host と一致していることを確認します

ジョブが停止またはブロックされている

eve job show <job-id>
eve job dep list <job-id>

依存関係を解決するか、適切な場合は eve job update でフェーズを更新してください。

古い試行の復旧機能は、すべての担当者とエージェントランタイムの正常なシャットダウンに対応するようになり、エージェントランタイムの Pod が停止しても試行が取り残されなくなりました。最近の再起動後もジョブが停止しているように見える場合は、手動で介入する前に復旧ループが一巡するまで待ってください。通常は自動的に再取得されます。

チャットルートが一致しない

チャットルートのマッチングでは、正規表現側で大文字と小文字を区別しなくなりました。それでもルートが機能しない場合、問題は大文字・小文字ではなく、パターン自体にあると考えられます。チャット設定の match 正規表現をもう一度確認し、マニフェストを再同期してください。

エージェントランタイムによる組織の検出

エージェントランタイムは起動時に組織を自動検出するため、org_default 設定エントリは不要になりました。新しいデプロイで組織のジョブが見つからない場合は、その組織に少なくとも 1 つのプロジェクトとエージェントが登録されていることを確認してから、エージェントランタイムのログを確認してください。存在しない org_default を探す必要はありません。

デプロイ後にアプリへアクセスできない

• デプロイジョブが成功したことを確認します（eve job result）。
• ingress のホストパターンを検証します：{service}.{orgSlug}-{projectSlug}-{env}.{domain}。
• サービスのポートが x-eve.ingress.port と一致していることを確認します。

エスカレーション

CLI の出力だけでは不十分な場合は、次の情報を収集します。

• eve system health
• eve job diagnose <job-id>
• マニフェストの差分（最近の変更）

その後、プラットフォームオペレーターに引き継ぎます。