# トラブルシューティング

> 症状別の解決策: キューで止まったジョブ、空のダッシュボード、表示されないインサイト、ブロックされたサインインなど。

Source: https://latchkey.dev/ja/documentation/troubleshooting

## Summary

- ジョブが**キュー**で止まる = ラベル、モニタリング、設定、請求、イメージビルド、または同時実行のいずれか。この順序で確認してください。
- 空のダッシュボードは、ほぼ常にデータの消失ではなくフィルターやバックフィルのタイミングが原因です。
- ブロックされた状態には必ず明確な兆候があります: バナー、通知ベル、または請求モーダルのバッジです。

以下の各セクションは1つの症状を扱い、確認する価値が高い順に原因を並べています。ほとんどの問題はどこかで自らを知らせます: ダッシュボードのバナー、ベルの通知、またはモーダルのステータスです。この表は、まずどこを見ればよいかを示します。

| 症状 | 最初に確認すること | 場所 |
| --- | --- | --- |
| ランナーを対象とするジョブがキューのままになる | 正確なラベル文字列 | Latchkey Runnersページの「Your runners」テーブル |
| ダッシュボードにデータが表示されない | リポジトリが選択されているか | すべての分析ページ上部のフィルターバー |
| AIインサイトがない | 処理中バナーと分析ブランチ | Insightsページとモニタリングモーダル |
| ランナーの起動がブロックされる | トライアル、サブスクリプション、無料枠の状態 | 請求モーダルと「Managed runner blocked」通知 |
| アクセスが突然ブロックされる | サブスクリプションのステータス(トライアル終了、Past Due、Canceled) | アクティベーション画面または請求モーダル |

## Latchkeyランナーを対象とするジョブがキューのままになる

これは、ランナーのプロビジョニングを妨げるあらゆる事象に共通する症状です。GitHubは、一致するラベルを持つランナーがジョブを取得するまでジョブを「キュー」に保ちます。そしてLatchkeyが起動をブロックまたはルーティングできない場合、GitHub側にエラーは表示されず、ジョブは単に待機します。つまり診断は常にLatchkey側で行われます。何も問題がないときにプロビジョニングがウォームピックアップとコールドスタートのどちらを選ぶかについては、[プロビジョニングの仕組み](/documentation/runner-provisioning)を参照してください。次の順序でトリアージしてください:

1. **ラベルのタイプミスを除外する** ラベルは正確に `latchkey-small`、`latchkey-medium`、`latchkey-large`、`latchkey-xlarge`、またはカスタムラベルのいずれかである必要があります。**確認方法:** Latchkey Runnersページの「Your runners」テーブルには正確な文字列が表示されます。ワークフローファイルと1文字ずつ比較してください(余分なスペースや誤ったハイフン1つでも一致しなくなります)。両方のラベル形式は同一にルーティングされるため、`runs-on: latchkey-small` と `runs-on: [self-hosted, latchkey-small]` は同じように動作します。配列形式が問題ではありません。
2. **リポジトリが監視されていることを確認する** マネージドランナーは監視されているリポジトリのみを扱うため、監視されていないリポジトリからのジョブは永遠に待機します。**確認方法:** ダッシュボードのサイドバーからモニタリングモーダルを開き(オーナーおよび管理者)、リポジトリのトグルを確認します。プランのリポジトリ上限に達している場合、それ以上のトグルはブロックされ、モーダルがアップグレードを案内します。[リポジトリの管理](/documentation/managing-repositories)を参照してください。
3. **ランナー設定が有効になっているか確認する** 無効な設定は新しいジョブの受け付けを停止し、そのラベルを対象とするジョブはキューに入ります。**確認方法:** [Runnersページ](/documentation/runners-dashboard)の設定行に、プリセットとカスタムランナーの両方について有効/無効の状態が表示されます。
4. **トライアル、サブスクリプション、無料枠の状態を確認する** 期限切れのトライアル、失効した(past dueまたはcanceled)サブスクリプション、またはカードなしトライアルで使い切った無料枠は、いずれも新しいランナーの起動をブロックします。**確認方法:** 通知ベルで「Managed runner blocked」通知を探し、請求モーダルを開きます。ステータスバッジ(Trial、Active、Past Due、Canceled)と無料枠ゲージが、どのケースかを示します。サブスクライブするか、Stripeポータルで支払い方法を修正すると、起動が即座に復元されます。[ランナーの使用状況と無料分](/documentation/runner-usage-and-free-minutes)を参照してください。
5. **カスタムイメージがまだビルド中かどうか確認する** 新しいカスタム設定を対象とするジョブは、そのイメージのビルドが完了するまで待機します。**確認方法:** Runnersページの設定行にイメージのビルドステータスが表示され、ランナーの準備が完了した際("AI scan runner is ready")、またはビルドが失敗した際に通知されます。[カスタムランナー](/documentation/custom-runners)を参照してください。
6. **同時実行の上限を確認する** すでに20のジョブが実行中の場合(workspaceごとのデフォルト上限。アイドル状態のウォームランナーはカウントされません)、それ以上のジョブは空きを待ちます。**確認方法:** これは多数のワークフローがリポジトリ全体で一度に発火したときに現れ、実行中のジョブが終わるにつれてキューに入ったジョブが自動的に開始します。より高い上限も利用可能です。[制限と同時実行](/documentation/runner-limits)を参照してください。

> ****
> 止まったジョブはGitHubのUIから安全にキャンセルできます。原因を修正したら再実行してください。キューの状態は何も残りません。

## ダッシュボードにデータが表示されない

空のダッシュボードは、ほぼ常にフィルターやタイミングを意味し、データの消失ではありません。次の順序で確認してください:

1. **リポジトリが選択されていない。** フィルターバーはすべての分析ページを駆動し、何も選択されていない場合はリポジトリの選択を促します。**確認方法:** 上部のフィルターバーにあるリポジトリセレクターを確認します。フィルターが混乱した状態にある場合は、**Reset filters** でデフォルトに戻せます。
2. **バックフィルがまだ実行中。** 新しく有効化されたリポジトリは、まず最近の履歴をインポートし、ほとんどのチームは数分以内にデータを目にします。**確認方法:** インポートが完了するまでバックフィルの進捗バナーがダッシュボードに表示されます。バナーが消えるのを待ってからページを判断してください。
3. **期間内に実行がない。** バックフィルは過去30日間の完了した実行を対象とし、日付範囲フィルターは実際のアクティビティと重なる必要があります。**確認方法:** GitHubでリポジトリの最近のワークフロー実行を確認します。直近の実行がバックフィル期間より前の場合、新しい実行が発生するまでページは空のままです。データが不足していると結論づける前に、日付範囲ピッカーを広げてください。
4. **アプリが誤った組織にインストールされている。** GitHub Appがリポジトリを所有する組織にインストールされていない場合、イベントはまったく届きません。**確認方法:** GitHubで組織のSettings、次にGitHub Appsを開き、Latchkeyがそこに表示されていることを確認します。正しい組織にインストールして修正してください。[GitHub Appのインストール](/documentation/install-the-github-app)を参照してください。

## AIインサイトが表示されない

インサイトの生成は自動かつイベント駆動であり、押すボタンはありません。エージェントは、新しく監視されたリポジトリの初回バックフィル後、分析ブランチでワークフローファイルが変更されたとき、連続した繰り返し失敗のとき、コストの急増のとき、そしてパフォーマンスの低下のときに実行されます。したがって「インサイトがない」は通常、トリガーがまだ発火していないか、エージェントがあなたとは異なるブランチを見ていることを意味します:

- **分析がまだ実行中、またはまだトリガーされていない。** インサイトはバックフィル完了後に自動的に生成されます。**確認方法:** エージェントの実行中、Insightsページに処理中バナーが表示されます。新しいリポジトリには数分の余裕を与えてください。
- **分析ブランチが誤っている。** 分析は、モニタリングモーダルで選択された**分析ブランチ**(デフォルトではリポジトリのデフォルトブランチ)に従います。他のブランチにのみ存在するワークフローは分析されません。**確認方法:** モニタリングモーダルを開き、リポジトリの横にあるブランチピッカーを確認します。[リポジトリの管理](/documentation/managing-repositories)を参照してください。
- **本当に言うことが少ない。** 小規模またはめったに実行されないワークフローは、推奨事項がほとんど生成されないことがあります。これは失敗ではなく1つの発見です。ワークフローファイルを編集すると分析が再トリガーされるため、次のワークフロー変更後に再度確認してください。

## 推奨事項の適用が失敗した、または変更が破棄された

推奨事項は、分析時点で存在していたワークフローファイルに対して生成されます。それ以降にファイルが変更された場合(あなたの編集や、以前にマージされたLatchkeyのPR)、一部の推奨事項はきれいには適用できなくなります:

- Latchkeyは、まだ適合するものでPRを開き、手動での配置が必要な推奨事項を一覧表示します。PRは `latchkey/insight-<detector>-<hex>` ブランチ上で「Latchkey insight: <what it does>」というタイトル(例:「Latchkey insight: pin GitHub Actions to commit SHAs」)で届き、成功バナーが直接そこへのリンクを提供します。
- 選択したすべての推奨事項が破棄された場合、古いセットを再試行しないでください。ワークフローを編集すると新しい分析がトリガーされます。それが完了するのを待ち(Insightsページの処理中バナーが消えます)、新しいセットから適用してください。[最適化インサイト](/documentation/optimization-insights)を参照してください。

## 支払いが失敗し、アクセスがブロックされた

**Past Due** ステータスは支払いの失敗を意味します: 支払い方法がStripeポータルで修正されるまで、ダッシュボードとAPIへのアクセスがブロックされ、ランナーの起動が停止します。Stripeポータルでは、支払い方法、請求書(PDF付き)、サブスクリプションの詳細が管理されます。代わりにサブスクリプションが **Canceled** の場合、アクセスはブロックされますが、再サブスクライブできるよう請求は引き続きアクセス可能です。いずれの場合もデータは保持されます。ステータスとその影響は[サブスクリプションの管理](/documentation/managing-billing)に一覧されています。

## スマートフォンでダッシュボードを使えない

これは現時点では仕様です: ダッシュボードはデスクトップ専用であり、モバイルおよびタブレットのブラウザはサインイン後にブロック通知を表示します。メール、Slack、プッシュによる[通知](/documentation/notifications)、および週次ダイジェストが、デスクを離れているときもあなたをカバーします。

## 個人アカウントにアプリをインストールした

個人アカウントはサポートされていません。Latchkeyはそのインストールを自動的に削除したため、片付けるものはありません。オンボーディングを再試行し、GitHubの**組織**を選択してください。個人アカウントしか持っていない場合は、まず組織を作成し(GitHubでは無料)、リポジトリをそこに移動してください。詳細は[GitHub Appのインストール](/documentation/install-the-github-app)にあります。

## トライアルが終了し、すべてがブロックされた

データは無傷です。ブロックはアクセスに対してであり、ストレージに対してではありません。ダッシュボードは「Your free trial has ended」画面に置き換えられ、APIアクセスは同じメッセージでブロックされ、マネージドランナーの起動はブロックされます(`latchkey-*` ラベルを対象とするジョブはエラーになるのではなくGitHubでキューのままになります)。アクティベーション画面(または到達できる場合は請求モーダル)からサブスクライブすると、ランナーの起動を含むアクセスが即座に復元されます。トライアルはworkspaceごとに1回実行されるため、サブスクライブやプラン変更によって再開されることはありません。[プランと無料トライアル](/documentation/plans-and-trial)を参照してください。

## まだ解決しませんか?

[FAQ](/documentation/faq)には手早い回答があります。それ以外については、[サポート](/support)に進むか、ダッシュボードのサイドバーで **Send Feedback** を使用してください。どちらも直接チームに届きます。

### ジョブが queued のまま止まっています。最初に確認すべきことは?

次の順に 6 点を確認してください。ランナーのラベル、リポジトリが監視対象かどうか、ランナー構成、請求状態、進行中のイメージビルド、同時実行の上限です。それぞれに明示的な兆候があるため、推測するよりリストを順に追う方が早く原因にたどり着けます。

### ダッシュボードが空です。データはどこへ行きましたか?

ほとんどの場合、データが失われたのではなく、フィルターバーかバックフィルのタイミングが原因です。まず期間を広げ、リポジトリとワークフローのフィルターを解除してください。新しいワークスペースなら、直近 30 日分の取り込みがまだ進行中の可能性があります。

### GitHub App を個人アカウントにインストールしてしまいました。どうすれば?

Latchkey は Organization を必要とするため、個人アカウントへのインストールは利用できません。無料の Organization を作成し、リポジトリを移管したうえでそこにアプリをインストールしてください。トライアルや収集済みのデータは、失敗したインストールではなくワークスペースに紐づきます。

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt