compose-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compose Doctor

Compose诊断工具

Diagnose and fix broken Compose apps. Workflow-oriented: we walk through auth → app identification → status → logs → secrets → wallets → manifest → diagnosis → fix.

诊断并修复故障Compose应用。采用工作流导向：我们将逐步引导完成身份验证 → 应用识别 → 状态检查 → 日志查看 → 密钥检查 → 钱包检查 → 清单验证 → 诊断 → 修复。

Boundaries

适用范围

Diagnose and fix EXISTING Compose apps interactively.
Do not build new apps — use
```
/compose
```
for that.
Do not serve as a CLI/manifest reference — use
```
/compose-reference
```
.
For secrets creation/management mechanics, use
```
/secrets
```
. But DO check whether required secrets exist as part of diagnosis.
Do not handle Turbo pipeline problems — use
```
/turbo-doctor
```
.

交互式诊断并修复已存在的Compose应用。
不支持构建新应用 — 请使用
```
/compose
```
。
不充当CLI/清单参考工具 — 请使用
```
/compose-reference
```
。
如需了解密钥创建/管理机制，请使用
```
/secrets
```
。但必须在诊断过程中检查所需密钥是否存在。
不处理Turbo流水线问题 — 请使用
```
/turbo-doctor
```
。

Mode Detection

模式检测

Before running any commands, check if you have the

Bash

tool available:

If Bash is available (CLI mode): Execute commands directly and parse output.
If Bash is NOT available (reference mode): Output commands for the user to run. Ask them to paste the output back so you can analyze it and provide recommendations.

在运行任何命令前，检查是否可用

Bash

工具：

若Bash可用（CLI模式）：直接执行命令并解析输出。
若Bash不可用（参考模式）：输出供用户运行的命令。请用户粘贴输出结果，以便分析并提供建议。

Diagnostic Workflow

诊断工作流

Step 1 — Verify Auth

步骤1 — 验证身份验证

goldsky project list 2>&1

. If not logged in, use

/auth-setup

goldsky project list 2>&1

。若未登录，请使用

/auth-setup

。

Step 2 — Identify the App

步骤2 — 识别应用

goldsky compose list

. Confirm the app exists and note its current status.

goldsky compose list

。确认应用存在并记录其当前状态。

Step 3 — Check Status

步骤3 — 检查状态

goldsky compose status -n <app>

goldsky compose status -n <app> --json

Possible statuses: RUNNING, PAUSED, ERROR, STARTING, STOPPED, PROVISIONING. Decision tree:

RUNNING but misbehaving → Step 4 (logs).
ERROR → Step 4 (logs) is the fastest path.
PAUSED → ask if intentional.
```
goldsky compose resume -n <app>
```
if not.
STARTING for >5 minutes → Step 4. (Use
```
.updated_at
```
from
```
--json
```
output to compute how long.)
NOT_FOUND → typo in the name? Or deployed to a different project / token.

goldsky compose status -n <app>

或

goldsky compose status -n <app> --json

。

可能的状态：RUNNING、PAUSED、ERROR、STARTING、STOPPED、PROVISIONING。决策树：

RUNNING但行为异常 → 步骤4（日志）。
ERROR → 步骤4（日志）是最快路径。
PAUSED → 询问是否为有意操作。若否，执行
```
goldsky compose resume -n <app>
```
。
STARTING状态持续超过5分钟 → 步骤4。（使用
```
--json
```
输出中的
```
.updated_at
```
计算时长。）
NOT_FOUND → 名称拼写错误？或部署到了其他项目/令牌下。

Step 4 — Examine Logs

步骤4 — 检查日志

goldsky compose logs -n <app> --tail 200 --json 2>&1

(add

-f

to stream,

--level error,warn

to filter,

--since 1h

for a window,

--search <term>

for text match).

How to match errors: scan the full log text (NDJSON

.message

field when

--json

is set) for exact substring against the first column of the error table below. Log lines include a

dashboard_url

attribute pointing to the specific run in the dashboard — surface it to the user alongside the diagnosis.

goldsky compose logs -n <app> --tail 200 --json 2>&1

（添加

-f

以流式查看，

--level error,warn

过滤日志级别，

--since 1h

指定时间范围，

--search <term>

进行文本匹配）。

错误匹配方式： 扫描完整日志文本（使用

--json

时为NDJSON格式的

.message

字段），与下方错误表第一列的精确子字符串匹配。日志行包含

dashboard_url

属性，指向控制台中对应的运行记录 — 诊断时需将该链接同步展示给用户。

Step 5 — Check Secrets

步骤5 — 检查密钥

If logs show missing-secret or auth errors:

bash

goldsky compose secret list -n <app>

Cross-reference against the manifest's

secrets:

array. Use

/secrets

goldsky compose secret set

to fix.

若日志显示密钥缺失或身份验证错误：

bash

goldsky compose secret list -n <app>

与清单中的

secrets:

数组交叉核对。使用

/secrets

或

goldsky compose secret set

修复。

Step 6 — Check Wallets / Gas

步骤6 — 检查钱包/Gas

If logs show wallet or transaction errors:

bash

goldsky compose wallet list -n <app>

Check whether the error is:

"No bundler provider available for chain <id>" → unsupported chain for gas sponsorship; either use a different chain or set
```
sponsorGas: false
```
and fund the EOA manually.
"You cannot use a smart wallet in local dev…" → switch to
```
compose dev --fork-chains
```
or use a BYO EOA wallet locally.
"Transaction Receipt failed with status reverted" → onchain revert. Open the
```
dashboard_url
```
from the log line — the run trace in the dashboard includes the decoded revert reason.

若日志显示钱包或交易错误：

bash

goldsky compose wallet list -n <app>

检查错误类型：

"No bundler provider available for chain <id>" → Gas赞助不支持该链；可更换链或设置
```
sponsorGas: false
```
并手动为EOA充值。
"You cannot use a smart wallet in local dev…" → 切换至
```
compose dev --fork-chains
```
或在本地使用自备EOA钱包。
"Transaction Receipt failed with status reverted" → 链上交易回滚。打开日志行中的
```
dashboard_url
```
— 控制台中的运行追踪包含解码后的回滚原因。

Step 7 — Check Manifest

步骤7 — 检查清单

If logs show

Manifest validation failed: …

, the manifest was rejected at deploy time. Common causes are in the error table below.

若日志显示

Manifest validation failed: …

，说明清单在部署时被拒绝。常见原因见下方错误表。

Step 8 — Diagnose + Fix

步骤8 — 诊断 + 修复

Present findings in this format:

undefined

按以下格式呈现结果：

undefined

Diagnosis

诊断结果

App: <name> Status: <status> Root cause: <one-line explanation> Fix: <one-line action, with exact command if possible> Verify: <how to confirm it worked>


**If the fix is mechanical** (secret set, manifest edit, redeploy), execute it and re-run Steps 3–4 to verify. **If the fix requires user input** (contract revert reason, funding decision, API key rotation), surface the diagnosis and stop.

应用： <名称> 状态： <状态> 根本原因： <一行说明> 修复方案： <一行操作建议，尽可能包含精确命令> 验证方式： <确认修复成功的方法>


**若修复为机械操作**（设置密钥、编辑清单、重新部署），执行操作后重新运行步骤3–4验证。**若修复需要用户输入**（合约回滚原因、充值决策、API密钥轮换），仅展示诊断结果即可停止流程。

Common Error Patterns

常见错误模式

Log / error message	Cause	Fix
`Manifest validation failed: api_version is required for deployment.`	Missing `api_version` at top of compose.yaml	Add `api_version: stable` (or a semver)
`Manifest validation failed: api_version "<v>" is not valid.`	Bad version value	Use `stable` , `preview` , `canary` , or semver
`Project name must start with a letter…`	Manifest `name` violates RFC 1123	lowercase, letters/numbers/hyphens, letter-start
`<task>.name must start with a letter or underscore…`	Task name regex fail	match `/^([a-zA-Z]\|_[a-zA-Z0-9])[a-zA-Z0-9_]*$/`
`<task>.triggers[N].authentication must be either 'auth_token' or 'none'`	HTTP trigger auth wrong	set to one of the two values
`<task>.triggers[N].network must be in snake_case format`	onchain_event network name wrong case	`polygon_amoy` , `ethereum_mainnet` (snake_case)
`<task>.triggers[N].contract must be a valid EVM address`	bad 0x address	check checksum + 40 hex chars
`<task>.triggers[N].ip_whitelist[N] must be a valid IP or CIDR`	malformed IP	fix format
`Secret names must be in SCREAMING_SNAKE_CASE format`	bad secret name	`MY_SECRET` , not `my-secret`
`Secret name "<X>" in .env is reserved for the app's postgres database`	secret clashes with hosted DB name (uppercased app name)	rename the secret
`The following secrets are referenced in the manifest but are not set in your local .env file`	local dev missing secret	add to `.env` or `goldsky compose secret set --env local`
`Deploy blocked: required secrets are missing from cloud`	cloud secret missing	`goldsky compose secret set` or `deploy --sync-env`
`Task bundling failed: <msg>`	esbuild compile error	fix the TS error in the task
`esbuild native binary crashed… architecture mismatch…`	arm/amd64 mismatch	rebuild image; `rm -rf ~/.cache/esbuild`
`You cannot use a smart wallet in local dev unless you use chain forking.`	Smart wallet in plain `compose dev`	`compose dev --fork-chains` or switch to a BYO EOA
`No bundler provider available for chain <id>.`	chain not supported by any bundler	change chains, or set `sponsorGas: false`
`Chain <id> is not supported by Alchemy's bundler.`	forced Alchemy on wrong chain	unset `BUNDLER_PROVIDER` env override
`Transaction Receipt failed with status reverted`	onchain revert	open `dashboard_url` for decoded revert reason
`Cannot deserialize params: chain <id> not found`	reorg replay for a chain missing in viem/chains	update the CLI / switch chains
`[Warning] onReorg is not supported for gas-sponsored transactions.`	non-fatal warning	if reorg matters, switch to non-sponsored
`[Warning] The 'nonce' parameter is being ignored for gas-sponsored transactions.`	passing `nonce` to sponsored send	remove the nonce override

日志/错误消息	原因	修复方案
`Manifest validation failed: api_version is required for deployment.`	compose.yaml顶部缺失 `api_version` 字段	添加 `api_version: stable` （或语义化版本号）
`Manifest validation failed: api_version "<v>" is not valid.`	版本值无效	使用 `stable` 、 `preview` 、 `canary` 或语义化版本号
`Project name must start with a letter…`	清单 `name` 违反RFC 1123规范	使用小写字母、数字、连字符，且以字母开头
`<task>.name must start with a letter or underscore…`	任务名称不符合正则要求	匹配正则 `/^([a-zA-Z]\|_[a-zA-Z0-9])[a-zA-Z0-9_]*$/`
`<task>.triggers[N].authentication must be either 'auth_token' or 'none'`	HTTP触发器身份验证配置错误	设置为 `auth_token` 或 `none` 之一
`<task>.triggers[N].network must be in snake_case format`	链上事件的网络名称格式错误	使用 `polygon_amoy` 、 `ethereum_mainnet` （蛇形命名法）
`<task>.triggers[N].contract must be a valid EVM address`	0x地址格式错误	检查校验和及40位十六进制字符
`<task>.triggers[N].ip_whitelist[N] must be a valid IP or CIDR`	IP格式错误	修正格式
`Secret names must be in SCREAMING_SNAKE_CASE format`	密钥名称格式错误	使用 `MY_SECRET` ，而非 `my-secret`
`Secret name "<X>" in .env is reserved for the app's postgres database`	密钥名称与托管数据库名称冲突（应用名称大写形式）	重命名密钥
`The following secrets are referenced in the manifest but are not set in your local .env file`	本地开发环境缺失密钥	添加至 `.env` 或执行 `goldsky compose secret set --env local`
`Deploy blocked: required secrets are missing from cloud`	云端环境缺失必要密钥	执行 `goldsky compose secret set` 或 `deploy --sync-env`
`Task bundling failed: <msg>`	esbuild编译错误	修复任务中的TypeScript错误
`esbuild native binary crashed… architecture mismatch…`	arm/amd64架构不匹配	重建镜像；执行 `rm -rf ~/.cache/esbuild`
`You cannot use a smart wallet in local dev unless you use chain forking.`	在普通 `compose dev` 中使用了智能钱包	执行 `compose dev --fork-chains` 或切换至自备EOA钱包
`No bundler provider available for chain <id>.`	无打包商支持该链	更换链，或设置 `sponsorGas: false`
`Chain <id> is not supported by Alchemy's bundler.`	强制在不支持的链上使用Alchemy打包商	取消 `BUNDLER_PROVIDER` 环境变量覆盖
`Transaction Receipt failed with status reverted`	链上交易回滚	打开 `dashboard_url` 查看解码后的回滚原因
`Cannot deserialize params: chain <id> not found`	viem/chains中缺失对应链导致重组重放错误	更新CLI / 更换链
`[Warning] onReorg is not supported for gas-sponsored transactions.`	非致命警告	若重组影响重大，切换至非赞助模式
`[Warning] The 'nonce' parameter is being ignored for gas-sponsored transactions.`	向赞助交易传入了 `nonce` 参数	移除nonce覆盖参数

Dashboard

控制台

Every app has a dashboard page:

https://app.goldsky.com/<project_id>/dashboard/compose/<app-name>

. Every run has

…/runs/<run_id>

. When diagnosing, surface both links to the user.

每个应用都有对应的控制台页面：

https://app.goldsky.com/<project_id>/dashboard/compose/<app-name>

。每次运行记录的链接为

…/runs/<run_id>

。诊断时需将这两个链接展示给用户。

When Bash is Not Available

当Bash不可用时

If you don't have the Bash tool, output the diagnostic commands for the user to run, but structure them clearly:

Give one command at a time.
Explain what to look for in the output.
Based on their description of the output, proceed with the diagnosis.

This is the fallback path — always prefer running commands directly when Bash is available.

若无法使用Bash工具，输出供用户运行的诊断命令，但需清晰结构化：

一次给出一个命令。
说明需关注输出中的哪些内容。
根据用户描述的输出结果，继续诊断流程。

这是 fallback 路径 — 当Bash可用时，始终优先直接运行命令。

Important Rules

重要规则

Don't redeploy without reading logs first — the error is almost always already in there.
Pause (not delete) before investigating.
```
goldsky compose pause
```
stops task execution without tearing down state.
```
--delete-database
```
on
```
compose delete
```
is irreversible — triple-check before running.
If a deploy is stuck at "Provisioning infra…" for >5 minutes on a first deploy, that's normal. For redeploys, it should be fast.

未查看日志前不要重新部署 — 错误几乎都已记录在日志中。
排查前先暂停（而非删除）应用。
```
goldsky compose pause
```
会停止任务执行但不会销毁状态。
```
compose delete
```
命令中的
```
--delete-database
```
参数不可逆 — 运行前务必再三确认。
首次部署时，若"Provisioning infra…"状态持续超过5分钟属于正常情况。重新部署时该过程应很快。

compose-doctor

Original

Translation

Compose Doctor

Compose诊断工具

Boundaries

适用范围

Mode Detection

模式检测

Diagnostic Workflow

诊断工作流

Step 1 — Verify Auth

步骤1 — 验证身份验证

Step 2 — Identify the App

步骤2 — 识别应用

Step 3 — Check Status

步骤3 — 检查状态

Step 4 — Examine Logs

步骤4 — 检查日志

Step 5 — Check Secrets

步骤5 — 检查密钥

Step 6 — Check Wallets / Gas

步骤6 — 检查钱包/Gas

Step 7 — Check Manifest

步骤7 — 检查清单

Step 8 — Diagnose + Fix

步骤8 — 诊断 + 修复

Diagnosis

诊断结果

Common Error Patterns

常见错误模式

Dashboard

控制台

When Bash is Not Available

当Bash不可用时

Important Rules

重要规则

Related

相关工具