Errors in Substrate-based chains are usually accompanied by descriptive messages. However, to read these messages, a tool parsing the blockchain data needs to request chain metadata from a node. That metadata explains how to read the messages. One such tool with a built-in parser for chain metadata is the Polkadot-JS Apps UI.
If this page does not answer your question, try searching for your problem at the Polkadot Knowledge Base for more information on troubleshooting your issue.
Here's how to find out the detailed error description through Polkadot-JS Apps.
A typical failed transactions looks something like this:
The image displays only the error name as defined in the code, not its error message. Despite this error being rather self-explanatory, let's find its details.
In the explorer tab, find the block in which this failure occurred. Then, expand the system.ExtrinsicFailed frame:
Notice how the details field contains a human-readable description of the error. Most errors will have this, if looked up this way.
This block is a live example of the above.
If you cannot look up the error this way, or there is no message in the details field, consult the table below.
Polkascan and Subscan show the ExtrinsicFailed event when a transaction does not succeed (example). This event gives us the error and index indices of the error but does not give us a nice message to understand what it means. We will look up the error in the codebase ourselves to understand what went wrong.
First, we should understand that the index number is the index of the pallet in the runtime from which the error originated. The error is likewise the index of that pallet's errors which is the exact one we're looking for. Both of these indices start counting from 0.
For example, if index is 5 and error is 3, as in the example linked above, we need to look at the runtime for the fourth error (index 3) in the sixth pallet (index 5).
By looking at the runtime code we see that the pallet at index 5 is Balances. Now we will check the Balances pallet's code which is hosted in the Substrate repository, and look for the fourth error in the Error enum. According to its source the error that we got is InsufficientBalance, or in other words, "Balance too low to send value".
The table below lists the most commonly encountered errors and ways to resolve them.
FUTURE ERROR
This error will not cause the TX to be discarded immediately. Instead, it will be sent to the futures queue, where it will wait to be executed at the correct place in the nonce sequence OR it will get discarded due to some other error (ex. the validity period expires).*
The below table is a reference to the errors that exists in Polkadot. It is generated from the runtime's metadata.
| Error | Description | Solution |
|---|---|---|
| Pallet | Error | Documentation |
|---|---|---|
