Troubleshooting
Diagnostic index for TRON developer issues — broadcast / RPC errors, smart-contract execution errors, node operations issues, plus FAQ, security guidance, and community support channels.
When something on TRON does not behave as expected, the right diagnostic page depends on where the symptom appears. Use this index to jump straight to the relevant chapter.
Diagnostic map
| Symptom | Confirm first | Recommended entry |
|---|---|---|
Broadcast API returns SIGERROR | Whether the transaction is signed by the correct private key and whether Permission_id matches the account permission | Broadcast and RPC errors, Transaction signature validation |
Broadcast API returns TAPOS_ERROR | Whether the block referenced by ref_block_bytes / ref_block_hash is still on the canonical chain | Broadcast and RPC errors, Transactions |
Broadcast API returns TRANSACTION_EXPIRATION_ERROR | Whether construction, signing, and broadcast exceeded the transaction expiration window | Sign and broadcast — the API workflow |
Broadcast returns result: true, but no receipt is found | Whether the transaction is still in mempool, expired, or accepted only by another node | Confirmation semantics, Broadcast and RPC errors |
Receipt receipt.result is not SUCCESS | Whether Energy is insufficient, the contract reverted, ABI encoding is wrong, or TVM execution failed | Smart contract errors, FeeLimit & Energy cost |
| TRC-20 transfer is on-chain but not detected | Whether you parse receipt log[] and decode the Transfer(address,address,uint256) event | Confirmation semantics, Internal transactions |
| Contract-derived TRX or TRC-10 transfer is not detected | Whether you parse internal_transactions[] and whether the node or indexer records internal transactions | Internal transactions, Broadcast and RPC errors |
| TronGrid returns 429, 403, 503, or incomplete results | Whether API key, QPS, pagination cursor, time window, and retry backoff are configured correctly | TronGrid rate limits, Broadcast and RPC errors |
| Self-hosted node block height stops advancing or node state looks abnormal | Node synchronization, database state, P2P connections, and startup warm-up status | Node operations issues |
By symptom
| Symptom | Recommended entry |
|---|---|
Transaction broadcast returns an error code (SIGERROR, BANDWITH_ERROR, CONTRACT_VALIDATE_ERROR, TAPOS_ERROR, DUP_TRANSACTION_ERROR, TRANSACTION_EXPIRATION_ERROR, SERVER_BUSY, …) | Broadcast and RPC errors |
| TronGrid or a self-hosted RPC service returns HTTP 503, connection timeouts, or rate-limit errors | Broadcast and RPC errors — 503 rate limits and service unavailable |
| Broadcast succeeds and returns a transaction hash, but the transaction is not included after several block intervals | Broadcast and RPC errors — transaction not included |
Smart-contract execution result is FAILED, or the receipt receipt.result is OUT_OF_ENERGY, OUT_OF_TIME, REVERT, BAD_JUMP_DESTINATION, STACK_*, JVM_STACK_OVER_FLOW, etc. | Smart contract errors |
Solidity-level revert reason needs Error(string) payload decoding | Smart contract errors — REVERT decoding |
Self-hosted node sync is slow, sync stops, logs show different resultCode, or LevelDB is corrupted | Node operations issues |
Lite Fullnode query rejections, such as this API is closed because this node is a lite fullnode | Node operations issues |
By knowledge type
| If you want… | Read |
|---|---|
Quick answers to common dev questions (resource calculation, fee_limit semantics, parsing raw_data_hex, burn addresses, …) | FAQ |
| To understand the threat model, common scams, how to verify official channels | Security and scam prevention |
| Community channels and where to ask for help | Community support and resources |
Related resources
- API task map — choose concept docs and API reference pages by development task
- Confirmation semantics — troubleshoot broadcast success without confirmation, missing receipts, and final-state mismatches
- Broadcast and RPC errors — every broadcast response code documented (the canonical destination for
CONTRACT_VALIDATE_ERROR-style codes) - Smart contract errors — every TVM execution result code, with decoding flow for
Error(string)reverts and Solidity custom errors - Node operations issues — sync issues,
different resultCodefailures, LevelDB / RocksDB picks, Lite Fullnode behavior - FAQ — the broader Q&A page (reference + diagnostic pointers)
- Security and scam prevention
- Community support and resources
Updated 8 days ago