Solana 交易失败时返回的错误信息经常没什么用。"Custom: 0x1771" 只给你一个数字、不告诉你具体哪里错了。生产环境 debug 时,把这种失败模式翻译成真正的根因,是你能掌握的杠杆最高的技能之一。
这篇覆盖怎么 debug 失败 Solana 交易:常见错误模式、工具、把神秘失败变成清晰根因的工作流。
常见失败类别
大多数 Solana 交易失败属于几类:
Compute 超过。 ComputationalBudgetExceeded。交易需要的 CU 比预算多。
滑点超过。 AMM/程序自定义错误。交易最小输出条件没达到。
余额不够。 听起来显而易见,但加上 priority fee 和(可选的)Jito tip 之后容易忽略。
账户不存在。 ATA 没创建;程序需要不存在的账户。
账户验证失败。 程序特定。传账户的类型或状态错。
Blockhash 过期。 交易用的 blockhash 已经不在最近窗口里了。
交易太大。 1232 字节限制;复杂交易撞。
自定义程序错误。 每个程序定义自己的错误码;码没通用意义。
每类有不同 debug 方法。
读错误
典型失败响应:
{
"err": {
"InstructionError": [
0,
{ "Custom": 6000 }
]
}
}
解码:
InstructionError意味着具体某条指令失败[0, ...]意味着第一条指令(0 索引)Custom意味着程序返回自定义错误码6000是错误码
要知道 6000 啥意思,你要程序的错误定义。Anchor 程序在 IDL 里有。非 Anchor 程序,查程序源码。
常见 Anchor 错误
Anchor 程序有标准错误码范围:
2000-2999:Anchor 框架错误3000+:自定义程序错误(程序定义)
几个常见 Anchor 框架码:
2000:InstructionMissing——指令未找到2003:ConstraintMut——账户标记不可变但程序试图修改2004:ConstraintHasOne——has_one约束失败2006:ConstraintRaw——原始约束失败(自定义检查)3008:AccountDidNotDeserialize——不能解码账户3010:AccountDiscriminatorMismatch——传错账户类型
看到这些,看你代码做错了什么(传错账户、缺签名等)。
常见 Token 程序错误
SPL Token 程序错误码:
1:余额不够4:所有者无效5:账户被不同程序拥有6:Mint 不匹配
转账和 swap 操作里常见。
Debug 工作流
实操 debug 工作流:
1. 拿签名。 从你代码日志或每笔签名级别遥测里。
2. 在 explorer 上找交易。 Solscan 或官方 Solana Explorer。有解析视图就看。
3. 读错误码。 用相关程序的错误定义解码。
4. 读日志。 Solana 程序能发日志消息。日志经常有人能读的"什么失败"提示。
5. 模拟交易。 能复现的,对当前状态模拟。模拟可能用更多上下文呈现同样错误。
6. 检查账户。 经常问题是账户在意外状态——错的所有者、错的大小、错的内容。
7. 能就本地复现。 Fork mainnet 状态在测试环境跑交易。
帮的工具
Solscan。 通用。解析常见交易;显示日志。
Solana Explorer。 规范参考;显示日志。
XRAY。 对一些交易类型解析更好。
Anchor IDL。 Anchor 程序;给你类型化的错误定义。
程序源码。 其他都失败时。GitHub 找程序、读错误定义。
你自己每笔签名级别遥测。 Explorer 没有的"失败前上下文"。
常见现实 debug 案例
我们见过的几个模式:
失败:swap 上 ConstraintRaw。 常是滑点容差违反。检查模拟和执行间价格变了没。
失败:多跳 swap 上 ComputationalBudgetExceeded。 CU 预算太低给实际路由。增到能处理最坏情况。
失败:用户首次交互 AccountNotFound。 ATA 没创建。加 init-if-needed 指令。
失败:重试后 BlockhashNotFound。 Blockhash 过期。重试时刷新 blockhash、别复用。
失败:Jupiter swap 上 Custom: 6000。 常是滑点。增容差或刷新 quote。
失败:交易模拟成功但执行失败。 模拟和执行间状态变。别信模拟是保证。
失败:sendTransaction 成功但交易不在链上。 Blockhash 过期、交易静默丢。轮询签名验证。
生产 debug 模式
生产代码:
每次发送捕获签名。 没它,后面查不了失败。
捕获完整指令上下文。 你提交了什么、你假设什么状态。
模拟了就捕获模拟结果。 有时模拟过、执行失败;差异信息丰富。
系统性抽样日志。 所有交易小百分比、完整上下文。给分析有用。
异常告警。 特定失败类型突然飙升,信号环境变了。
这周可以做什么
debug Solana 生产问题:
- 拿签名。 没它你就是猜。
- 先 Solscan 看。 解析视图经常有答案。
- 读程序错误定义。 别猜自定义错误码。
- 读日志。 程序经常会日志原因。
- 能就本地复现。 Fork mainnet 状态;跑交易。
- 系统性问题,看多个失败。 模式比单个案例信息丰富。
生产 debug 试一下 BoltTx
BoltTx 提供每笔签名级别的投递遥测——你提交的每笔交易,看何时被接收、何时中继、何时上链(或为什么没):
import { Connection } from "@solana/web3.js";
const connection = new Connection(
"https://bolttx.io/?api-key=YOUR_API_KEY",
"processed"
);
遥测帮区分"RPC 问题"、"链上失败"、"blockhash 过期"——每个有不同修法。免费档注册。
常见问题
我交易签名存在但交易没上链。怎么回事? 最可能 blockhash 在包含前过期。刷新 blockhash 重提。
"Custom: 6000"啥意思? 看程序。查程序错误定义(Anchor IDL 或源码)。
为什么模拟成功但执行失败? 模拟和执行间状态变了。别信模拟是保证——永远确认执行。
怎么找程序错误码? Anchor 程序看 IDL。原始程序看源码错误 enum。
Explorer 显示交易上链了但代码以为失败? 检查你确认逻辑。可能查错 commitment 等级或缺成功信号。