subgraph-doctor

Subgraph Doctor

CLI コマンドを実行し、ログを読み、根本原因を特定して修正を実行することで、既存の Goldsky Subgraph の問題を診断し、修正します。

対象範囲

• 既存のサブグラフの問題を診断し、修正します。
• 壊れているサブグラフ（失敗している、停止している、エラーが発生している、デプロイできない）のみを診断します。正常だが遅いサブグラフは最適化の対象です。/subgraph-builder（例：eth_calls の削減や宣言）を使用してください。
• 新しいサブグラフの構築やひな形の作成は行いません。作成、init、deploy には /subgraph-builder を使用してください。
• The Graph の移行には対応しません。/subgraph-migrate を使用してください。
• コマンドリファレンスとしては機能しません。CLI の構文やフラグの確認には、/subgraph-builder または goldsky subgraph <cmd> --help を使用してください。
• Turbo または Mirror のパイプラインには対応しません。/turbo-doctor または /mirror-doctor を使用してください。
• お客様向けの対応のみです。 goldsky CLI コマンド、ダッシュボード、GraphQL クエリのみを使用してください。内部 Goldsky ツールである graphman、kubectl、Datadog、データベースへの直接アクセスは決して提案しないでください。それらが必要な問題の場合は、サポートにエスカレーションしてください（ステップ 6 を参照）。

モードの判定

何かを実行する前に、Bash ツールが利用できるか確認してください。

• Bash を利用可能（CLI モード）： コマンドを直接実行し、出力を解析します。
• Bash を利用不可（リファレンスモード）： ユーザーに一度に 1 つずつコマンドを提示し、確認すべき内容を説明して、貼り付けられた結果に基づいて進めます。

診断ワークフロー

以下の手順を順番に実施してください。各手順は前の手順を踏まえて進みます。

ステップ 1：認証を確認する

ユーザーがログインしていることを確認するため、goldsky project list 2>&1 を実行します。

• ログイン済みの場合： プロジェクト名を確認し、続行します。
• 未ログインの場合： /auth-setup を案内します。認証が機能するまで先に進まないでください。

ステップ 2：サブグラフを特定する

すべてのサブグラフとそのステータスを一覧表示するため、goldsky subgraph list 2>&1 を実行します。

ユーザーがすでにサブグラフ（name/version）を指定している場合は、一覧に存在することを確認します。それ以外の場合は一覧を表示し、診断するサブグラフを尋ねます。そのステータスとインデックス対象のネットワークを確認してください。ネットワークの誤りは、最もよくある根本原因の 1 つです（ステップ 5 を参照）。

ステップ 3：症状に応じて切り分ける

サブグラフの問題はいくつかの種類に分けられます。症状に合った手順を選択してください。

症状	考えられる原因の種類	参照先
デプロイコマンドが失敗した（作成されなかった）	デプロイ時のエラー	ステップ 4 →「デプロイ時の失敗」
ブロック位置で停止／ヘッドが進まない／停滞／自動一時停止	インデックス処理の停滞	ステップ 4 → ログ + _meta
Error／failed のヘルス状態、インデックス処理が停止	ハンドラー／マッピングのエラー	ステップ 4 → ログ
移行中に低い進捗率で停止	最初からの同期（低速）、またはハンドラーエラー	ステップ 4 → ログ + _meta
エンドポイントが 404／データがない／クエリできない	エンドポイントまたは未同期	ステップ 4 → _meta + エンドポイントの確認
reached the subgraph limit、database unavailable、ログエラーがないまま停止	運用上の問題／クォータ（Goldsky 側）	ステップ 6（エスカレーション）

ステップ 4：診断データを収集する

以下を実行し、結論を出す前に分析してください。

# Errors only — START HERE. Widen the window (e.g. --since 24h) if nothing shows.
goldsky subgraph log <name/version> --since 1h --filter error 2>&1

# Subgraph + tag + deployment status
goldsky subgraph list <name/version> 2>&1

フィルターなしでログを取得しないでください。 サブグラフは info／debug レベルで大量のログを出力します。--filter error を付けずに goldsky subgraph log を実行すると、時間がかかり、トークンを大量に消費する一方、エラーフィルター適用後の表示に比べて有益な情報が増えることはほとんどありません。エラー以外のコンテキストが本当に必要な場合は、対象を絞ってください。短い時間範囲（--since 5m）を指定し、可能であれば特定の文字列を grep してください。まずエラーと、以下の _meta クエリを確認してください。

次に、GraphQL エンドポイントに対して**_meta クエリ**を実行します。これは「停止している」または「データがない」サブグラフを確認するうえで、最も有用なチェックです。最新のインデックス済みブロックが報告されます。

{
  _meta {
    deployment
    hasIndexingErrors
    block { number hash timestamp }
  }
}

• hasIndexingErrors: true → ハンドラー／マッピングのエラーによってインデックス処理が停止しています。以下のエラーパターンに進んでください。
• block.number がチェーンのヘッドより大幅に遅れている → まだ同期中（または停滞中）です。ブロックエクスプローラーと比較してください。
• block.number がチェーン上のブロックより先行している／まだ存在しない → 誤ったネットワークにデプロイされています（以下を参照）。

ステップ 5：エラーパターンを照合する

ネットワークの誤り／異なるチェーン上のコントラクト

症状： サブグラフがデータを生成しない、または _meta に、対象チェーンにはまだ存在しない開始ブロック／現在のブロックが表示されます。サブグラフ名から意図されたチェーンを推測できる場合もあります。

原因： マニフェストの network／チェーンスラッグが意図したものとは異なるチェーンを指しているため、まだマイニングされていないブロックをサブグラフが待ち続けています。

修正方法： subgraph.yaml の network を正しい値に修正し（サポート対象ネットワークのドキュメント docs.goldsky.com/chains/supported-networks で正確なチェーンスラッグを確認してください。例：litvm-testnet ではなく liteforge）、新しいバージョンをデプロイします。ブロックエクスプローラーで、コントラクトアドレスが対象チェーンに実際に存在することを確認してください。

デプロイ時のエラー

デプロイコマンドでエラーが発生し、何も作成されません。よくあるケースを以下に示します。

エラー／症状	原因	修正方法
no network <slug> found	subgraph.yaml のチェーンスラッグが誤っている、または存在しない	サポート対象ネットワークの正しいスラッグを使用します。
subgraph init で YAML の解析エラーが発生する	--contract-name に使用できない文字が含まれている（例：:, エクスプローラーのラベルに含まれる空白）	--contract-name PolymarketUMACTFAdapter のように、問題のない名前を指定します。
subgraph must use a single apiVersion across its data sources. Found: 0.0.7, 0.0.9	dataSources／templates 間で apiVersion が混在している	マニフェスト全体で apiVersion を統一します。
Interface '<X>' not defined	スキーマが未定義のインターフェースを参照している	schema.graphql でインターフェースを定義します。
時系列／集計仕様のエラー（must have id field of type Int8、@unique がない、aggregations not supported in spec version 1.0.0）	スキーマで、仕様バージョンに適合しない時系列／集計を使用している	id の型を Int8 に修正し、@unique を追加するか、集計を削除します。
A deployment with this name & version already exists	同じ name/version を再デプロイしている	バージョンを上げるか、goldsky subgraph delete <name/version> を実行してから再デプロイします。
Windows での CLI インストールが失敗する	インストーラーがネイティブの Windows ではなく WSL 上で実行されている	認証セットアップの scripts/install.ps1 を使用してください。WSL 内で npm を使用して、固定された CLI バージョンをインストールします。リモートのインストーラーをパイプで渡さないでください。

ハンドラー／マッピングのエラー（インデックス作成が停止）

症状： hasIndexingErrors: true が表示され、ログに次のような内容が記録されます。

• Mapping aborted at src/mappings/...: unexpected null in handler '<handler>' at block #<n>
• Subgraph error ... code: SubgraphSyncingFailure
• Token.load の失敗／Heap（メモリ不足）エラー
• WASM トラップ／「実行エラーのためハンドラーをスキップしました」（nonFatalErrors が有効な場合）

原因： 顧客の AssemblyScript マッピングにバグがあり、ほとんどの場合は null 参照が原因です。典型的なケースは、トークンの decimals()／symbol() がリバートしたとき（非 ERC-20 コントラクト）、ハンドラーが早期リターンしてエンティティを .save() しないため、後続のハンドラーがその欠落したエンティティを .load() しようとしてパニックすることです。

修正方法：

1. エラーからハンドラーとブロックを特定します。
2. null の場合にも .save() を省略しないようにマッピングを修正します（例：decimals に 18 などのセンチネル値を設定してエンティティを保存し、後続の価格計算はスキップします）。
3. 新しいバージョンをデプロイし、最初に影響を受けたブロックまで巻き戻して、欠落したエンティティを再初期化します。
4. 修正中にエンドポイントで（不完全な）データを提供し続けるための一時的な対策として、subgraphError: allow を指定すると、クエリで部分的な結果を返せます。

Goldsky 側の注意点：nonFatalErrors が有効な状態で発生した決定的なエラーは、根本原因を解決した後も自動的に解消されない場合があります。正しく再デプロイしてもサブグラフのエラーが続く場合は、エスカレーションしてください（ステップ 6）。

停止状態／自動一時停止されたサブグラフ

症状： ヘッドの進行が止まり、Goldsky が停止したサブグラフを自動で一時停止し、メールで通知します。

原因： 多くの場合、ハンドラーのエラー（上記を参照）です。ときには、一時的な上流 RPC の問題や、古くなったソースチェーンが原因です。

対処方法：

1. まず、ログと _meta でエラーを確認します。
2. コードのバグであれば、修正して再デプロイします。一時的な問題だった場合は、goldsky subgraph start <name/version> で再開します。
3. ソースチェーン自体が停止している（エクスプローラーでも新しいブロックがない）場合、インデックス対象はありません。チェーンが再開するまで待ちます。

上流 RPC のエラー

症状： eth_getLogs does not exist／未対応のメソッド、または Found no transaction for event／ブロック番号の不一致。

原因： チェーンの RPC プロバイダーに問題があるか、メソッドが不足しています。サブグラフが原因ではありません。（実際の事例：ノードがすべてのログにリクエストの fromBlock を設定していたため、graph-node がログとブロックを照合できず、致命的なエラーになりました。）

対処方法： Goldsky／RPC 側の問題です。マニフェストの問題ではないことを確認してから、正確なエラーとブロック番号を添えてエスカレーションします（ステップ 6）。

エンドポイント／クエリの問題

症状： GraphQL エンドポイントでの 404、「データなし」、またはレート制限エラー。

• 404／データなし： サブグラフの同期がまだ完了していない（_meta を確認）か、パブリックエンドポイントが無効になっている可能性があります。goldsky subgraph list <name/version> でエンドポイント URL を確認します。リソースが存在し、同期が完了する前にエンドポイントが利用可能だと決めつけないでください。
• パブリック／プライベート： クエリで認証エラーが発生する場合、エンドポイントがプライベートになっている可能性があります。goldsky subgraph update <name/version> --public-endpoint enabled で切り替えます（/subgraph-builder を参照）。
• レート制限： デフォルトでは約 10 秒あたり 50 リクエストです。より高い制限には営業／サポートへの問い合わせが必要です。エスカレーションし（ステップ 6）、具体的な新しい上限は約束しないでください。

ステップ 6：診断結果を提示する

## Diagnosis

**Subgraph:** <name/version>
**Network:** <chain>
**Symptom:** <one-line>

**Root cause:**
<what's wrong and why>

**Evidence:**
- <log line / _meta block number / error string>

**Recommended fix:**
1. <step>
2. <step>

**Prevention:**
<how to avoid it next time, if applicable>

[email protected] にエスカレーションする場合（推測で時間を浪費しないでください）：

• CLI では確認できない運用上の問題／クォータの問題：reached the subgraph limit（特に、表示される件数が間違っているように見える場合）、database unavailable、ログエラーがないままヘッドが停止している場合。
• 上流 RPC のバグ（eth_getLogs does not exist、ログ／ブロックの不一致）。
• 正しく修正して再デプロイしたことを確認済みなのに、エラー状態が続くサブグラフ。

ユーザーが送信するための正確な情報を伝えます。サブグラフの name/version、プロジェクト ID、GraphQL エンドポイント、エラー文字列、影響を受けたブロック番号です。優先対応を受けるため、AI／MCP を利用していることを伝えられる旨も案内します。

ステップ 7：修正を実行する

修正の実行を提案し、破壊的な操作を行う前に必ず確認します。

• 一時停止中のサブグラフを再開： goldsky subgraph start <name/version>
• メンテナンスのために一時停止： goldsky subgraph pause <name/version>
• 修正済みのバージョンを再デプロイ： goldsky subgraph deploy <name/new-version> --path .
• 巻き戻して再デプロイ： goldsky subgraph deploy <name/version> --start-block <firstAffectedBlock>
• 削除して再作成（最後の手段。最初から再インデックスするため、ユーザーに警告してください）： goldsky subgraph delete <name/version> を実行してから、再デプロイします。

修正後、goldsky subgraph list <name/version> と _meta クエリを再確認し、ヘッドが再び進行していることを確かめます。

よくあるマッピングコードの根本原因（再デプロイ前に確認）

ハンドラー／マッピングエラーでインデックス作成が停止した場合、根本原因はほぼ必ず次の AssemblyScript のミスのいずれかです。再デプロイする前にマッピングを確認し、今後デプロイに至らないよう、Subgraph Linter（静的解析）と Matchstick テストの利用を推奨してください（/subgraph-builder → references/testing.md を参照）。

根本原因	発生する症状	修正方法
Entity.load(id)! のチェックなしの強制アンラップ	エンティティが存在しない場合に unexpected null in handler パニックが発生	取得または作成する処理を使います。load を ! でアンラップしないでください。
.save() を省略する早期リターン（多くの場合、ERC-20 ではないトークンに対する decimals()／symbol() のリバート後）	後続の .load() がパニックする。Token.load／Heap エラーが発生する	try_ 呼び出しを使い、値をデフォルトに設定してエンティティを永続化し、後続の価格計算のみをスキップします。
ゼロチェックなしの除算	数学演算の中断／unexpected null	safeDiv でラップします（分母が 0 の場合は 0 を返します）。
ヘルパーがすでにエンティティを変更した後の古い .save()	フィールドが上書き／消去され、データが誤る（必ずしもクラッシュするとは限りません）	1 回だけ読み込み、変更を加えて、1 回だけ保存します。古いコピーを保存しないでください。
リバートする、または宣言されていないイベントごとの eth_call	インデックス作成が遅くなる、または unexpected null が発生する	リバートに対応できるようにし（try_）、宣言します（specVersion 1.2.0 以降）。

これらは、ステップ 5 の「ハンドラー／マッピングエラー」で示される事後的な症状の原因です。コードを修正し、影響を受けた最初のブロックまで巻き戻すことが、確実な解決策です。

重要なルール

• 診断の前に、必ずデータ（ログと _meta）を収集します。推測してはいけません。
• 「製品は安定しており、問題のほとんどは顧客側にあります」。Goldsky 側の問題だと考える前に、明らかな顧客側の原因（ネットワークの誤り、マッピングのバグ、スキーマ／マニフェストのエラー）をまず確認します。
• 顧客に graphman／kubectl／Datadog／データベースへのアクセスを勧めてはいけません。代わりにエスカレーションしてください。
• 破壊的なコマンド（削除、一からの再インデックス作成）を実行する前に、必ず確認を取ります。
• 再デプロイすると、新しい不変のバージョンが作成されます。フロントエンドの URL が変わらないようにタグを使います（/subgraph-builder を参照）。

Bash が利用できない場合

コマンドを 1 つずつ提示し、確認すべき点を説明して、ユーザーが貼り付けた出力に応じて進めます。Bash が利用できる場合は、必ずコマンドを直接実行する方法を優先してください。

関連項目

• /subgraph-builder — サブグラフの構築、作成、デプロイ。スキーマ／マッピング／マニフェストの作成、エンドポイント、タグ、Webhook
• /subgraph-migrate — The Graph からサブグラフを移行
• /auth-setup — CLI のインストールと認証
• /datasets — チェーンのプレフィックスとサポート対象ネットワークのスラッグ
• /turbo-doctor、/mirror-doctor — パイプライン（サブグラフではありません）の診断