Runtime Errors
v393Every failed extrinsic returns a DispatchError with one of 15 variants. Some variants wrap nested error
enums with more specific codes. In total there are 44 error variants across all levels.
How Runtime Errors Work
When an extrinsic fails, the runtime returns a DispatchError. This is a
Rust enum with 15 variants. Simple errors like BadOrigin are self-contained.
Others like Module, Token, and Arithmetic wrap a nested enum with more specific error codes.
Module errors are the most common. They come from individual pallets and require decoding the pallet index and error index to identify the specific error.
DispatchError Variants
| Index | Name | Description | Details |
|---|---|---|---|
| 0 | Other | Some unclassified error occurred | -- |
| 1 | CannotLookup | Failed to look up some data (account, storage key, etc.) | -- |
| 2 | BadOrigin | The origin of the call does not have the required permission | -- |
| 3 | Module nested | Pallet-specific error — decode via pallet index + error index to find the exact error | View |
| 4 | ConsumerRemaining | Cannot remove account: there are still consumers referencing it | -- |
| 5 | NoProviders | Cannot create account: there are no providers to allow creation | -- |
| 6 | TooManyConsumers | Cannot add a new consumer: the account has too many consumers | -- |
| 7 | Token nested | Token/balance operation failed — see nested TokenError | View |
| 8 | Arithmetic nested | Arithmetic operation failed — see nested ArithmeticError | View |
| 9 | Transactional nested | Transactional storage layer error — see nested TransactionalError | View |
| 10 | Exhausted | Resources exhausted (e.g., all allowable extrinsics weight consumed) | -- |
| 11 | Corruption | The state is corrupt; this is a bug in the runtime | -- |
| 12 | Unavailable | Some resource (e.g., a preimage) is unavailable right now | -- |
| 13 | RootNotAllowed | Root origin is not allowed for this operation | -- |
| 14 | Trie nested | Trie/proof verification error — see nested TrieError | View |
Nested Error Enums
These enums provide specific error codes when a DispatchError variant wraps additional detail.
TokenError
Errors related to token/balance operations
ArithmeticError
Errors from checked arithmetic operations
TransactionalError
Errors from the transactional storage layer
TrieError
Errors from Merkle trie proof verification
Module Errors
ModuleError
Wraps pallet-specific errors with pallet index and error bytes
For Developers
Decode a DispatchError from an extrinsic result:
// Using polkadot.js API
const tx = api.tx.subtensorModule.addStake(hotkey, amount);
const result = await tx.signAndSend(coldkey);
// Check for DispatchError
result.events.forEach(({ event }) => {
if (api.events.system.ExtrinsicFailed.is(event)) {
const [dispatchError] = event.data;
if (dispatchError.isModule) {
// Module error - decode pallet + error index
const decoded = api.registry.findMetaError(dispatchError.asModule);
console.log(`${decoded.section}.${decoded.name}: ${decoded.docs}`);
} else {
// Non-module error (BadOrigin, Token, Arithmetic, etc.)
console.log(dispatchError.toString());
}
}
});