subgraph-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subgraph Doctor

Subgraph 诊断工具

Diagnose and fix existing Goldsky Subgraph problems by running CLI commands, reading logs, identifying root causes, and executing fixes.

通过运行CLI命令、读取日志、定位根本原因并执行修复，来诊断和修复现有Goldsky Subgraph的问题。

Boundaries

适用边界

Diagnose and fix EXISTING subgraph problems.
Diagnose only subgraphs that are broken (failing, stalled, erroring, won't deploy). A healthy but slow subgraph is an optimization task — use
```
/subgraph-builder
```
(e.g. reducing/declaring eth_calls).
Do not build or scaffold new subgraphs — use
```
/subgraph-builder
```
for authoring/
```
init
```
/
```
deploy
```
.
Do not handle The Graph migrations — use
```
/subgraph-migrate
```
.
Do not serve as a command reference — use
```
/subgraph-builder
```
or
```
goldsky subgraph <cmd> --help
```
for CLI syntax and flag lookups.
Do not handle Turbo or Mirror pipelines — use
```
/turbo-doctor
```
or
```
/mirror-doctor
```
.
Customer-facing only. Use only
```
goldsky
```
CLI commands, the dashboard, and GraphQL queries. Never suggest
```
graphman
```
,
```
kubectl
```
, Datadog, or direct database access — those are internal Goldsky tooling. When a problem needs them, escalate to support (see Step 6).

诊断并修复已有的Subgraph问题。
仅诊断已损坏的Subgraph（运行失败、停滞、报错、无法部署）。健康但运行缓慢的Subgraph属于优化任务，请使用
```
/subgraph-builder
```
（例如减少/声明eth_calls）。
不要构建或搭建新的Subgraph——编写/
```
init
```
/
```
deploy
```
相关操作请使用
```
/subgraph-builder
```
。
不处理The Graph迁移相关问题——请使用
```
/subgraph-migrate
```
。
不作为命令参考——CLI语法和参数查询请使用
```
/subgraph-builder
```
或
```
goldsky subgraph <cmd> --help
```
。
不处理Turbo或Mirror流水线问题——请使用
```
/turbo-doctor
```
或
```
/mirror-doctor
```
。
仅面向客户使用。 仅可使用
```
goldsky
```
CLI命令、仪表盘和GraphQL查询。绝不要建议使用
```
graphman
```
、
```
kubectl
```
、Datadog或直接数据库访问——这些是Goldsky内部工具。当问题需要用到这些工具时，请升级到支持团队（见第6步）。

Mode Detection

模式检测

Before running anything, check if you have the

Bash

tool:

Bash available (CLI mode): Run commands directly and parse output.
Bash NOT available (reference mode): Give the user one command at a time, explain what to look for, and proceed based on what they paste back.

在执行任何操作前，先检查是否拥有

Bash

工具：

可用Bash（CLI模式）： 直接运行命令并解析输出。
不可用Bash（参考模式）： 每次给用户一条命令，解释需要关注的内容，再根据用户粘贴的返回结果继续处理。

Diagnostic Workflow

诊断工作流

Follow these steps in order. Each builds on the previous one.

请按顺序执行以下步骤，每一步都基于前一步的结果。

Step 1: Verify Authentication

第1步：验证身份认证

Run

goldsky project list 2>&1

to confirm the user is logged in.

If logged in: Note the project name and continue.
If not logged in: Direct the user to
```
/auth-setup
```
. Do not proceed until auth works.

运行

goldsky project list 2>&1

确认用户已登录。

已登录： 记录项目名称并继续。
未登录： 引导用户使用
```
/auth-setup
```
。在认证正常前不要继续下一步。

Step 2: Identify the Subgraph

第2步：定位目标Subgraph

Run

goldsky subgraph list 2>&1

to list all subgraphs and their status.

If the user already named a subgraph (

name/version

), confirm it exists in the list. Otherwise show the list and ask which one to diagnose. Note its status and which network it indexes — a wrong network is one of the most common root causes (see Step 5).

运行

goldsky subgraph list 2>&1

列出所有Subgraph及其状态。

如果用户已经指定了某个Subgraph（

name/version

格式），确认它存在于列表中。否则展示列表并询问要诊断哪一个。记录它的状态以及它索引的网络——网络错误是最常见的根本原因之一（见第5步）。

Step 3: Triage by Symptom

第3步：按症状分诊

Subgraph problems fall into a few families. Pick the path that matches the symptom:

Symptom	Likely family	Go to
Deploy command failed (never created)	Deploy-time error	Step 4 → "Deploy-time failures"
Stuck at a block / head not moving / stalled / auto-paused	Indexing stalled	Step 4 → logs + `_meta`
`Error` / `failed` health, indexing halted	Handler/mapping error	Step 4 → logs
Stuck at low % during a migration	Sync-from-scratch (slow), or handler error	Step 4 → logs + `_meta`
Endpoint 404 / no data / can't query	Endpoint or not-yet-synced	Step 4 → `_meta` + endpoint check
`reached the subgraph limit` , `database unavailable` , frozen with no log errors	Operational/quota (Goldsky-side)	Step 6 (escalate)

Subgraph问题可分为几大类。选择与症状匹配的处理路径：

症状	可能类别	处理步骤
部署命令失败（从未创建成功）	部署时错误	第4步 → "部署时故障"
卡在某个区块 / 头部不前进 / 停滞 / 自动暂停	索引停滞	第4步 → 日志 + `_meta`
健康状态为 `Error` / `failed` ，索引停止	处理器/映射错误	第4步 → 日志
迁移期间卡在低百分比	从头同步（速度慢），或处理器错误	第4步 → 日志 + `_meta`
端点404 / 无数据 / 无法查询	端点问题或尚未同步完成	第4步 → `_meta` + 端点检查
`reached the subgraph limit` 、 `database unavailable` 、无日志错误但卡住不动	运维/配额问题（Goldsky侧）	第6步（升级处理）

Step 4: Gather Diagnostic Data

第4步：收集诊断数据

Run these and analyze before concluding:

bash

undefined

运行以下命令并分析后再得出结论：

bash

undefined

Errors only — START HERE. Widen the window (e.g. --since 24h) if nothing shows.

仅查看错误 —— 从这里开始。如果没有结果，扩大时间窗口（例如 --since 24h）

goldsky subgraph log <name/version> --since 1h --filter error 2>&1

Subgraph + tag + deployment status

Subgraph + 标签 + 部署状态

goldsky subgraph list <name/version> 2>&1


> **Do not pull unfiltered logs.** Subgraphs emit a huge volume at `info`/`debug` level — running `goldsky subgraph log` without `--filter error` is slow and extremely token-hungry, and rarely adds signal over the error-filtered view. If you genuinely need non-error context, scope it tightly: a very short window (`--since 5m`) and, if possible, grep for a specific string. Lead with errors + the `_meta` query below.

Then run the **`_meta` query** against the GraphQL endpoint — this is the single most useful check for "stuck" or "no data" subgraphs. It reports the latest indexed block:

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

```
hasIndexingErrors: true
```
→ a handler/mapping error halted indexing. Go to the error patterns below.
```
block.number
```
far behind the chain head → still syncing (or stalled). Compare against a block explorer.
```
block.number
```
ahead of / not yet on the chain → wrong network deployed (see below).

goldsky subgraph list <name/version> 2>&1


> **不要拉取未过滤的日志。** Subgraph会产生大量`info`/`debug`级别的日志——不带`--filter error`运行`goldsky subgraph log`速度很慢且极其消耗token，相比错误过滤后的视图几乎不会增加有效信息。如果你确实需要非错误上下文，请严格限定范围：使用非常短的时间窗口（`--since 5m`），如果可能的话，用grep搜索特定字符串。优先使用错误日志 + 下方的`_meta`查询。

然后对GraphQL端点运行**`_meta`查询**——这是针对“卡住”或“无数据”Subgraph最有用的检查方式。它会返回最新的已索引区块信息：

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

```
hasIndexingErrors: true
```
→ 处理器/映射错误导致索引停止。请查看下方的错误模式。
```
block.number
```
远落后于链头部 → 仍在同步（或已停滞）。可与区块浏览器的数据对比。
```
block.number
```
超前于/尚未出现在链上 → 部署到了错误的网络（见下文）。

Step 5: Match Error Patterns

第5步：匹配错误模式

Wrong network / contract on the wrong chain

网络错误 / 合约部署在错误链上

Symptoms: Subgraph never produces data, or

_meta

shows a start/current block that doesn't exist yet on the target chain. Often the subgraph name hints at the intended chain.

Cause: The manifest's

network

/chain slug points at a different chain than intended, so the subgraph is waiting for blocks that haven't been mined.

Fix: Correct the

network

subgraph.yaml

(verify the exact chain slug against the supported-networks docs at

docs.goldsky.com/chains/supported-networks

— e.g. it's

liteforge

, not

litvm-testnet

) and redeploy a new version. Confirm the contract address actually exists on the target chain via a block explorer.

症状： Subgraph从不产生数据，或

_meta

显示的起始/当前区块在目标链上尚不存在。通常Subgraph名称会暗示预期的链。

原因： 清单文件中的

network

/链slug指向了非预期的链，因此Subgraph一直在等待尚未被挖出的区块。

修复方法： 修正

subgraph.yaml

中的

network

字段（通过

docs.goldsky.com/chains/supported-networks

的支持网络文档验证准确的链slug——例如正确的是

liteforge

，而非

litvm-testnet

），然后重新部署新版本。通过区块浏览器确认合约地址确实存在于目标链上。

Deploy-time failures

部署时故障

The deploy command errors out and nothing gets created. Common cases:

Error / symptom	Cause	Fix
`no network <slug> found`	Wrong/unknown chain slug in `subgraph.yaml`	Use the correct slug from supported networks.
YAML parse error from `subgraph init`	Illegal characters in `--contract-name` (e.g. `:` , spaces from an explorer label)	Pass a clean name: `--contract-name PolymarketUMACTFAdapter` .
`subgraph must use a single apiVersion across its data sources. Found: 0.0.7, 0.0.9`	Mixed `apiVersion` across `dataSources` / `templates`	Unify `apiVersion` across the whole manifest.
`Interface '<X>' not defined`	Schema references an undefined interface	Define the interface in `schema.graphql` .
Timeseries/aggregation spec errors ( `must have id field of type Int8` , `@unique` missing, `aggregations not supported in spec version 1.0.0` )	Schema uses timeseries/aggregations not valid for the spec version	Fix the `id` type to `Int8` , add `@unique` , or remove aggregations.
`A deployment with this name & version already exists`	Re-deploying the same `name/version`	Bump the version, or `goldsky subgraph delete <name/version>` then redeploy.
`curl ...	sh` install fails (Windows)	Install script is shell-only

部署命令报错，且没有创建任何资源。常见情况：

错误 / 症状	原因	修复方法
`no network <slug> found`	`subgraph.yaml` 中的链slug错误或未知	使用支持网络列表中的正确slug。
`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引用了未定义的接口	在 `schema.graphql` 中定义该接口。
时间序列/聚合规范错误（ `must have id field of type Int8` 、缺少 `@unique` 、 `aggregations not supported in spec version 1.0.0` ）	Schema使用了对应当前规范版本无效的时间序列/聚合功能	将 `id` 类型修正为 `Int8` 、添加 `@unique` ，或移除聚合功能。
`A deployment with this name & version already exists`	重复部署相同的 `name/version`	升级版本号，或执行 `goldsky subgraph delete <name/version>` 后重新部署。
`curl ...	sh`安装失败（Windows系统）	安装脚本仅支持shell

Handler / mapping errors (indexing halts)

处理器/映射错误（索引停止）

Symptoms:

hasIndexingErrors: true

; logs show things like:

Mapping aborted at src/mappings/...: unexpected null in handler '<handler>' at block #<n>

Subgraph error ... code: SubgraphSyncingFailure

```
Token.load
```
failures / Heap (out-of-memory) errors
WASM trap / "Handler skipped due to execution failure" (when
```
nonFatalErrors
```
is enabled)

Cause: A bug in the customer's AssemblyScript mappings — most often a null dereference. Classic case: an entity is never

.save()

d because the handler early-returns when a token's

decimals()

symbol()

reverts (non-ERC-20 contract), then a later handler

.load()

s that missing entity and panics.

Fix:

Identify the handler and block from the error.
Patch the mapping so it doesn't skip
```
.save()
```
on the null path (e.g. default
```
decimals
```
to a sentinel like
```
18
```
, persist the entity, skip downstream pricing).
Redeploy a new version and rewind to the first affected block so the missing entities re-initialize.
As a stopgap to keep the endpoint serving (incomplete) data while you fix it,
```
subgraphError: allow
```
lets queries return partial results.

Goldsky-side caveat: a deterministic error with
nonFatalErrors
enabled may not auto-clear even after the underlying cause is resolved. If a subgraph stays errored after a correct redeploy, escalate (Step 6).

症状：

hasIndexingErrors: true

；日志显示类似以下内容：

Mapping aborted at src/mappings/...: unexpected null in handler '<handler>' at block #<n>

Subgraph error ... code: SubgraphSyncingFailure

```
Token.load
```
失败 / 堆（内存不足）错误
WASM陷阱 / "Handler skipped due to execution failure"（当启用
```
nonFatalErrors
```
时）

原因： 客户的AssemblyScript映射代码存在bug——最常见的是空指针解引用。典型场景：当代币的

decimals()

symbol()

调用回退（非ERC-20合约）时，处理器提前返回，导致实体从未执行

.save()

，之后的处理器

.load()

这个不存在的实体时就会崩溃。

修复方法：

从错误信息中定位出问题的处理器和区块。
修复映射代码，确保在空值路径下不会跳过
```
.save()
```
（例如将
```
decimals
```
默认设为
```
18
```
这样的哨兵值，持久化实体，仅跳过下游的定价逻辑）。
重新部署新版本，并回退到第一个受影响的区块，以便重新初始化缺失的实体。
作为修复期间保持端点提供（不完整）数据的临时方案，可设置
```
subgraphError: allow
```
让查询返回部分结果。

Goldsky侧注意事项：启用
nonFatalErrors
时的确定性错误，即使根本原因已解决，也可能不会自动清除。如果Subgraph在正确重新部署后仍处于错误状态，请升级处理（第6步）。

Stalled / auto-paused subgraph

停滞/自动暂停的Subgraph

Symptoms: Head stops advancing; Goldsky auto-pauses a stalled subgraph and emails you.

Cause: Often a handler error (above), sometimes a transient upstream RPC issue or a stale source chain.

Fix:

Check logs and
```
_meta
```
for errors first.
If it's a code bug, fix and redeploy. If it was transient, resume:
```
goldsky subgraph start <name/version>
```
.
If the source chain itself is stale (no new blocks on the explorer either), there's nothing to index — wait for the chain.

症状： 区块头部停止前进；Goldsky会自动暂停停滞的Subgraph并向你发送邮件。

原因： 通常是处理器错误（见上文），有时是上游RPC临时问题或源链本身停滞。

修复方法：

首先检查日志和
```
_meta
```
查询是否有错误。
如果是代码bug，修复后重新部署。如果是临时问题，恢复运行：
```
goldsky subgraph start <name/version>
```
。
如果源链本身停滞（区块浏览器上也没有新区块），则没有可索引的内容——等待链恢复即可。

Upstream RPC errors

上游RPC错误

Symptoms:

eth_getLogs does not exist

/ method-not-supported, or

Found no transaction for event

/ block-number mismatches.

Cause: The chain's RPC provider is misbehaving or missing methods — not the subgraph. (Real case: a node stamped every log with the request's

fromBlock

, so graph-node couldn't match logs to blocks and went fatal.)

Fix: This is Goldsky/RPC-side. Confirm it's not a manifest issue, then escalate (Step 6) with the exact error and block number.

症状：

eth_getLogs does not exist

/ 方法不支持，或

Found no transaction for event

/ 区块号不匹配。

原因： 链的RPC提供商运行异常或缺少方法——而非Subgraph的问题。（真实案例：某个节点给每条日志都打上请求的

fromBlock

时间戳，导致graph-node无法将日志与区块匹配，进而触发致命错误。）

修复方法： 这是Goldsky/RPC侧的问题。确认不是清单文件的问题后，携带具体错误信息和区块号升级处理（第6步）。

Endpoint / query problems

端点/查询问题

Symptoms:

on the GraphQL endpoint, "no data", or rate-limit errors.

404 / no data: The subgraph may not be synced yet (check
```
_meta
```
), or the public endpoint is disabled. Verify the endpoint URL with
```
goldsky subgraph list <name/version>
```
. Don't assume an endpoint is live before the resource exists and has synced.
Public vs private: If queries fail auth, the endpoint may be private. Toggle with
```
goldsky subgraph update <name/version> --public-endpoint enabled
```
(see
```
/subgraph-builder
```
).
Rate limits: Default is ~50 requests / 10 seconds. Higher limits are sales/support-gated — escalate (Step 6); don't promise a specific new limit.

症状： GraphQL端点返回

、“无数据”或限流错误。

404 / 无数据： Subgraph可能尚未同步完成（检查
```
_meta
```
），或公共端点已禁用。通过
```
goldsky subgraph list <name/version>
```
验证端点URL。不要在资源存在且同步完成前假设端点已可用。
公共 vs 私有： 如果查询因认证失败，端点可能是私有的。可通过
```
goldsky subgraph update <name/version> --public-endpoint enabled
```
切换（见
```
/subgraph-builder
```
）。
限流： 默认限制约为每10秒50次请求。更高的限额需要销售/支持团队审批——请升级处理（第6步）；不要承诺具体的新限额。

Step 6: Present Diagnosis

第6步：输出诊断结果

undefined

undefined

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:

<step>
<step>

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


**When to escalate to support@goldsky.com** (don't burn cycles guessing):
- Operational/quota issues not visible via CLI: `reached the subgraph limit` (especially if the count looks wrong), `database unavailable`, frozen head with no log errors.
- Upstream RPC bugs (`eth_getLogs does not exist`, log/block mismatches).
- A subgraph that stays errored after a verified-correct redeploy.

Give the user the exact info to send: subgraph `name/version`, project ID, the GraphQL endpoint, the error string, and the affected block number. Mention they can reference using the AI/MCP for priority handling.

Subgraph： <name/version> 网络： <chain> 症状： <一句话描述>

根本原因： <问题所在及原因说明>

证据：

<日志行 / _meta区块号 / 错误字符串>

建议修复方案：

<步骤>
<步骤>

预防措施： <如果适用，说明下次如何避免>


**何时升级到support@goldsky.com**（不要浪费时间猜测）：
- CLI无法查看的运维/配额问题：`reached the subgraph limit`（尤其是数量看起来不对时）、`database unavailable`、无日志错误但区块头部卡住不动。
- 上游RPC bug（`eth_getLogs does not exist`、日志/区块不匹配）。
- 经过验证正确的重新部署后，Subgraph仍处于错误状态。

告知用户需要发送的具体信息：Subgraph的`name/version`、项目ID、GraphQL端点、错误字符串以及受影响的区块号。说明他们可以提及使用AI/MCP以获得优先处理。

Step 7: Execute Fix

第7步：执行修复

Offer to run fixes, and confirm before anything destructive:

Resume a paused subgraph:
```
goldsky subgraph start <name/version>
```
Pause for maintenance:
```
goldsky subgraph pause <name/version>
```

Redeploy a fixed version:

goldsky subgraph deploy <name/new-version> --path .

Redeploy with a rewind:

goldsky subgraph deploy <name/version> --start-block <firstAffectedBlock>

Delete and recreate (last resort, reindexes from scratch — warn the user):
```
goldsky subgraph delete <name/version>
```
then redeploy.

After a fix, re-check

goldsky subgraph list <name/version>

and the

_meta

query to confirm the head is advancing again.

主动提出执行修复，并在执行任何破坏性操作前确认：

恢复暂停的Subgraph：
```
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

查询，确认区块头部再次前进。

Common mapping-code root causes (catch before redeploy)

常见映射代码根本原因（重新部署前排查）

When indexing halted on a handler/mapping error, the underlying cause is almost always one of these AssemblyScript mistakes. Check the mapping for them before redeploying — and recommend the Subgraph Linter (static analysis) plus Matchstick tests so they never reach a deploy again (see

/subgraph-builder

→

references/testing.md

Root cause	Symptom it produces	Fix
Unchecked `Entity.load(id)!` force-unwrap	`unexpected null in handler` panic when the entity is missing	Use get-or-create; never `!` -unwrap a `load` .
Early-return that skips `.save()` (often after a reverting `decimals()` / `symbol()` on a non-ERC-20)	later `.load()` panics; `Token.load` /Heap errors	Use `try_` calls, default the value, persist the entity, skip only downstream pricing.
Division without a zero guard	math abort / `unexpected null`	Wrap in a `safeDiv` (return 0 when denominator is 0).
Stale `.save()` after a helper already mutated the entity	overwritten/clobbered fields, wrong data (not always a crash)	Load once, mutate, save once; don't save a stale copy.
Per-event `eth_call` that reverts or is undeclared	slow indexing or `unexpected null`	Make it revert-safe ( `try_` ) and declare it ( `specVersion 1.2.0` +).

These are the causes behind the reactive symptoms in Step 5's "Handler / mapping errors". Fixing the code and rewinding to the first affected block is the durable fix.

当索引因处理器/映射错误停止时，根本原因几乎总是以下AssemblyScript错误之一。重新部署前请检查映射代码中是否存在这些问题——并推荐使用Subgraph Linter（静态分析）和Matchstick测试，避免这些问题进入部署环节（见

/subgraph-builder

→

references/testing.md

）：

根本原因	产生的症状	修复方法
未检查的 `Entity.load(id)!` 强制解包	实体不存在时触发 `unexpected null in handler` 崩溃	使用get-or-create模式；绝不要对 `load` 的结果使用 `!` 解包。
提前返回导致跳过 `.save()` （通常发生在非ERC-20合约的 `decimals()` / `symbol()` 调用回退后）	后续 `.load()` 触发崩溃； `Token.load` /堆错误	使用 `try_` 调用，设置默认值，持久化实体，仅跳过下游定价逻辑。
没有零值防护的除法	数学运算中止 / `unexpected null`	封装为 `safeDiv` （分母为0时返回0）。
辅助函数已经修改实体后，又执行了过时的 `.save()`	字段被覆盖/冲突，数据错误（不一定会崩溃）	只加载一次，修改后保存一次；不要保存过时的副本。
每个事件的 `eth_call` 调用回退或未声明	索引缓慢或 `unexpected null`	使其具备回退安全性（ `try_` ）并声明该调用（ `specVersion 1.2.0` 及以上版本）。

这些是第5步“处理器/映射错误”中反应性症状背后的根本原因。修复代码并回退到第一个受影响的区块是持久的解决方案。

Important Rules

重要规则

Always gather data (logs +
```
_meta
```
) before diagnosing. Never guess.
"The product is solid — most issues are customer-side." Check the obvious customer causes first (wrong network, mapping bug, schema/manifest error) before assuming a Goldsky-side problem.
Never recommend
```
graphman
```
/
```
kubectl
```
/Datadog/database access to a customer. Escalate instead.
Confirm before destructive commands (delete, reindex from scratch).
Redeploying creates a new immutable version. Use tags so the frontend URL doesn't change (see
```
/subgraph-builder
```
).

诊断前务必先收集数据（日志 +
```
_meta
```
），绝不要猜测。
“产品是稳定的——大多数问题出在客户端。” 在假设是Goldsky侧的问题前，先检查明显的客户端原因（网络错误、映射bug、schema/清单文件错误）。
绝不要向客户推荐
```
graphman
```
/
```
kubectl
```
/Datadog/数据库访问，应升级处理。
执行破坏性命令（删除、从头重新索引）前务必确认。
重新部署会创建一个新的不可变版本。使用标签可以保持前端URL不变（见
```
/subgraph-builder
```
）。

When Bash Is Not Available

当Bash不可用时

Give one command at a time, explain what to look for, and proceed based on the user's pasted output. Always prefer running commands directly when Bash is available.

每次给用户一条命令，解释需要关注的内容，再根据用户粘贴的输出继续处理。当Bash可用时，始终优先直接运行命令。

subgraph-doctor

Original

Translation

Subgraph Doctor

Subgraph 诊断工具

Boundaries

适用边界

Mode Detection

模式检测

Diagnostic Workflow

诊断工作流

Step 1: Verify Authentication

第1步：验证身份认证

Step 2: Identify the Subgraph

第2步：定位目标Subgraph

Step 3: Triage by Symptom

第3步：按症状分诊

Step 4: Gather Diagnostic Data

第4步：收集诊断数据

Errors only — START HERE. Widen the window (e.g. --since 24h) if nothing shows.

仅查看错误 —— 从这里开始。如果没有结果，扩大时间窗口（例如 --since 24h）

Subgraph + tag + deployment status

Subgraph + 标签 + 部署状态

Step 5: Match Error Patterns

第5步：匹配错误模式

Wrong network / contract on the wrong chain

网络错误 / 合约部署在错误链上

Deploy-time failures

部署时故障

Handler / mapping errors (indexing halts)

处理器/映射错误（索引停止）

Stalled / auto-paused subgraph

停滞/自动暂停的Subgraph

Upstream RPC errors

上游RPC错误

Endpoint / query problems

端点/查询问题

Step 6: Present Diagnosis

第6步：输出诊断结果

Diagnosis

诊断结果

Step 7: Execute Fix

第7步：执行修复

Common mapping-code root causes (catch before redeploy)

常见映射代码根本原因（重新部署前排查）

Important Rules

重要规则

When Bash Is Not Available

当Bash不可用时

Related

相关技能