Decode a historical Substrate module error with matching metadata

A failed extrinsic can identify its pallet and error by numbers. Those numbers depend on runtime metadata and may acquire a different meaning after an upgrade.

Capture the typed dispatch error

Find system.ExtrinsicFailed among the target extrinsic’s events. Its first data item is a DispatchError. Use event records decoded with the runtime appropriate to that execution, retaining the original block and extrinsic index alongside the object named error below.

if (error.isModule) {
  const decoded = error.registry.findMetaError(error.asModule)
  console.log(decoded.section, decoded.name, decoded.docs.join(" "))
} else {
  console.log(error.toString())
}

Keep raw data when metadata is unavailable

For a module error, store the resolved section, name and docs together with its raw bytes. For example, identical numeric pallet indices on two separate parachains need not refer to the same pallet. A generic dispatch error bypasses the module lookup and can be recorded by its enum variant.

If historical data has been pruned, retain the undecoded error and retrieve matching metadata before displaying a diagnosis. A guessed error name can send an operator to the wrong subsystem.

Sources