故障排查概览
TRON 开发者故障排查索引,按报错环节和信息类型分流到各专项文档：交易广播与 RPC 错误、智能合约运行时错误、全节点运维问题,以及 FAQ、安全指南与社区支持通道。
接入或运维 TRON 网络时遇到异常,排查起点取决于异常发生的环节和表现症状。本页按症状分类,直接跳转到对应的专项排查文档。
故障定位地图
| 你看到的现象 | 先确认什么 | 推荐入口 |
|---|---|---|
广播接口返回 SIGERROR | 交易签名是否来自正确私钥，Permission_id 是否匹配账户权限 | 广播与 RPC 错误诊断、交易签名校验 |
广播接口返回 TAPOS_ERROR | ref_block_bytes / ref_block_hash 引用的区块是否仍在规范链上 | 广播与 RPC 错误诊断、交易协议 |
广播接口返回 TRANSACTION_EXPIRATION_ERROR | 构建、签名和广播之间是否超过交易有效期 | 交易签名与广播——API 工作流 |
广播返回 result: true，但迟迟查不到 receipt | 交易是否仍在 mempool、是否过期、是否被其他节点接受 | 确认语义、广播与 RPC 错误诊断 |
receipt 中 receipt.result 不是 SUCCESS | 是否 Energy 不足、合约 revert、参数编码错误或 TVM 执行异常 | 智能合约异常排查、合约调用与能量计费 |
| TRC-20 转账已上链但未被识别 | 是否解析 receipt 的 log[]，是否按 Transfer(address,address,uint256) Event 解码 | 确认语义、内部交易 |
| 合约派生的 TRX / TRC-10 转账未被识别 | 是否解析 internal_transactions[]，节点或索引器是否开启内部交易记录 | 内部交易、广播与 RPC 错误诊断 |
| TronGrid 返回 429、403、503 或结果不完整 | API key、QPS、分页游标、时间窗口和重试退避是否正确 | TronGrid 速率限制、广播与 RPC 错误诊断 |
| 自建节点区块高度不前进或状态异常 | 节点同步、数据库、P2P 连接和启动预热状态 | 节点运维常见故障排查 |
按报错环节与表现症状检索
| 问题表现与症状 | 推荐排查页面 |
|---|---|
调用交易广播接口时返回了异常错误码（如 SIGERROR、BANDWITH_ERROR、CONTRACT_VALIDATE_ERROR、TAPOS_ERROR、DUP_TRANSACTION_ERROR、TRANSACTION_EXPIRATION_ERROR、SERVER_BUSY 等） | 广播与 RPC 错误诊断 |
| TronGrid 或自建 RPC 服务返回 HTTP 503 报错、连接超时或频次限制限流 | 广播与 RPC 错误诊断——503 限流处理 |
| 交易调用广播接口成功返回了交易哈希，但在等待数个出块时间后依然未能成功打包上链 | 广播与 RPC 错误诊断——交易未上链 |
智能合约执行结果返回 FAILED，或交易收据中 receipt.result 返回 OUT_OF_ENERGY、OUT_OF_TIME、REVERT、BAD_JUMP_DESTINATION、STACK_*、JVM_STACK_OVER_FLOW 等虚拟机执行错误 | 智能合约异常排查 |
合约调用触发 Solidity 层的 Revert 异常，需要对其 Error(string) 报错载荷进行 Hex 解码 | 智能合约异常排查——REVERT 解码 |
自建全节点区块同步缓慢、同步完全停止、日志报错提示 different resultCode 或 LevelDB 数据库发生损坏 | 节点运维常见故障排查 |
轻节点（Lite FullNode）发起历史查询时返回被拒绝的报错（如 this API is closed because this node is a lite fullnode） | 节点运维常见故障排查 |
按技术文档与知识类型检索
| 开发与运维目标 | 推荐参考页面 |
|---|---|
快速解答开发中常见的概念问题（如资源消耗计算、fee_limit 作用、如何手动解析 raw_data_hex 字段、全网常用燃烧地址等） | 常见问题解答 (FAQ) |
| 了解 TRON 网络威胁模型、防范各类钓鱼与漏洞诈骗套路、掌握安全的钱包签名规范 | TRON 安全与防骗指南 |
| 寻找社区交流渠道、提报 Bug、参与协议 TIP 改进提议投票或寻求社区开发者帮助 | 社区支持与技术资源 |
相关资源
- API 任务地图：按开发任务选择概念文档和落地 API 页面。
- 确认语义：排查广播成功但未确认、Receipt 不存在或最终状态判断不一致的问题。
- 广播与 RPC 错误诊断:广播环节响应码清单,含
CONTRACT_VALIDATE_ERROR详细解析。 - 智能合约异常排查:TVM 运行时错误分类，以及如何解码
Error(string)与 Solidity 自定义错误。 - 节点运维常见故障排查:区块同步缓慢、
different resultCode报错、启动预热以及只读查询节点配置。 - 常见问题解答 (FAQ)：概念与参考类问题技术手册。
- TRON 安全与防骗指南
- 社区支持与技术资源
Updated 11 days ago