Skip to content

Commit 8912721

Browse files
raymondkfcheungraymondkfcheung
committed
Update Failure Event Handling
1 parent 63711c9 commit 8912721

File tree

3 files changed

+95
-30
lines changed

3 files changed

+95
-30
lines changed

‎.snippets/code/tutorials/interoperability/xcm-observability/execution-with-error.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<div class="termynal" data-termynal>
2+
<pre data-ty>
3+
"error": {
4+
"type": "Module",
5+
"value": {
6+
"type": "PolkadotXcm",
7+
"value": {
8+
"type": "LocalExecutionIncompleteWithError",
9+
"value": {
10+
"index": 0,
11+
"error": {
12+
"type": "FailedToTransactAsset"
13+
}
14+
}
15+
}
16+
}
17+
}
18+
</pre>
19+
</div>

‎llms.txt‎

Lines changed: 47 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -27877,10 +27877,7 @@ This scenario demonstrates how a `SetTopic` is included or generated, how to ide
2787727877

2787827878
### Launch a Fork for Local Testing
2787927879

27880-
To illustrate the tracing of XCM, fork the relevant chains locally using Chopsticks.
27881-
27882-
* No runtime override or logging configuration is needed
27883-
* You may use a Chopsticks config file if desired
27880+
To see XCM tracing in action, fork the relevant chains locally using Chopsticks.
2788427881

2788527882
→ See the [Fork a Chain with Chopsticks guide](/tutorials/polkadot-sdk/testing/fork-live-chains/){target=\_blank} for step-by-step instructions.
2788627883

@@ -28101,7 +28098,7 @@ Run it locally:
2810128098
npx tsx limited-reserve-transfer-assets.ts
2810228099
```
2810328100

28104-
#### Local XCM (origin chain: Polkadot Asset Hub)
28101+
#### Local XCM (Origin Chain: Polkadot Asset Hub)
2810528102

2810628103
The submitted extrinsic constructs an XCM like the following:
2810728104

@@ -28117,7 +28114,7 @@ The submitted extrinsic constructs an XCM like the following:
2811728114
</pre>
2811828115
</div>
2811928116

28120-
#### Forwarded XCM (destination chain: Acala)
28117+
#### Forwarded XCM (Destination Chain: Acala)
2812128118

2812228119
During execution, the runtime adds a `SetTopic` instruction automatically. This topic is carried through to the destination chain and becomes the basis for event correlation:
2812328120

@@ -28178,21 +28175,56 @@ The runtime automatically inserts a `SetTopic` instruction (if not manually prov
2817828175

2817928176
### Failure Event Handling
2818028177

28181-
If your XCM fails, you can debug using one of the following:
28178+
When an XCM fails, the entire execution is **rolled back**, so no failure events are emitted on-chain. However, you can still observe and debug the failure using two main approaches:
28179+
28180+
#### View Nested Errors from Indexers
28181+
28182+
Most indexers (and API responses) will show **nested dispatch errors** such as:
28183+
28184+
<div class="termynal" data-termynal>
28185+
<pre data-ty>
28186+
"error": {
28187+
"type": "Module",
28188+
"value": {
28189+
"type": "PolkadotXcm",
28190+
"value": {
28191+
"type": "LocalExecutionIncompleteWithError",
28192+
"value": {
28193+
"index": 0,
28194+
"error": {
28195+
"type": "FailedToTransactAsset"
28196+
}
28197+
}
28198+
}
28199+
}
28200+
}
28201+
</pre>
28202+
</div>
28203+
28204+
This output is available on runtimes from **`stable2506` or later**, and is often sufficient for identifying common issues like missing assets or execution limits.
28205+
28206+
#### Use Chopsticks for Full Error Logs
28207+
28208+
For deeper analysis:
2818228209

28183-
### View Nested Errors
28210+
* Use Chopsticks to **replay the message with logging enabled**
28211+
* See exactly **which instruction failed**, and why
28212+
* View full error chains like `FailedToTransactAsset`, or `AssetNotFound`
2818428213

28185-
Most indexers show the outermost error (e.g., `LocalExecutionIncompleteWithError`), which is often enough to understand basic failures.
28214+
This is especially useful when dealing with:
2818628215

28187-
### Use Chopsticks for Full Logs
28216+
* Multi-hop XCMs
28217+
* Custom asset locations
28218+
* Execution mismatches or weight issues
2818828219

28189-
With logging enabled, Chopsticks will show:
28220+
→ For replay setup, see [Replay and Dry Run XCMs Using Chopsticks](/tutorials/interoperability/replay-and-dry-run-xcms/){target=\_blank}.
2819028221

28191-
* Which instruction failed
28192-
* Full error chain (e.g., `FailedToTransactAsset`, `AssetNotFound`)
28193-
* Precise reason for rollback or halt
28222+
#### Recommended Debugging Workflow
2819428223

28195-
→ Useful for understanding weight failures, malformed assets, or execution mismatches.
28224+
1. **Start with indexer or API output** to inspect dispatch errors.
28225+
2. If unclear, **replay using Chopsticks** to trace message steps.
28226+
3. **Inspect logs** to pinpoint the failing instruction and error.
28227+
4. Adjust asset location, weight, or execution logic accordingly.
2819628228

2819728229
## Step 5: Handle Older Runtimes
2819828230

‎tutorials/interoperability/xcm-observability.md‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,7 @@ This scenario demonstrates how a `SetTopic` is included or generated, how to ide
5757

5858
### Launch a Fork for Local Testing
5959

60-
To illustrate the tracing of XCM, fork the relevant chains locally using Chopsticks.
61-
62-
* No runtime override or logging configuration is needed
63-
* You may use a Chopsticks config file if desired
60+
To see XCM tracing in action, fork the relevant chains locally using Chopsticks.
6461

6562
→ See the [Fork a Chain with Chopsticks guide](/tutorials/polkadot-sdk/testing/fork-live-chains/){target=\_blank} for step-by-step instructions.
6663

@@ -97,13 +94,13 @@ Run it locally:
9794
npx tsx limited-reserve-transfer-assets.ts
9895
```
9996

100-
#### Local XCM (origin chain: Polkadot Asset Hub)
97+
#### Local XCM (Origin Chain: Polkadot Asset Hub)
10198

10299
The submitted extrinsic constructs an XCM like the following:
103100

104101
--8<-- 'code/tutorials/interoperability/xcm-observability/local-xcm.html'
105102

106-
#### Forwarded XCM (destination chain: Acala)
103+
#### Forwarded XCM (Destination Chain: Acala)
107104

108105
During execution, the runtime adds a `SetTopic` instruction automatically. This topic is carried through to the destination chain and becomes the basis for event correlation:
109106

@@ -132,21 +129,38 @@ The runtime automatically inserts a `SetTopic` instruction (if not manually prov
132129

133130
### Failure Event Handling
134131

135-
If your XCM fails, you can debug using one of the following:
132+
When an XCM fails, the entire execution is **rolled back**, so no failure events are emitted on-chain. However, you can still observe and debug the failure using two main approaches:
133+
134+
#### View Nested Errors from Indexers
135+
136+
Most indexers (and API responses) will show **nested dispatch errors** such as:
137+
138+
--8<-- 'code/tutorials/interoperability/xcm-observability/execution-with-error.html'
139+
140+
This output is available on runtimes from **`stable2506` or later**, and is often sufficient for identifying common issues like missing assets or execution limits.
141+
142+
#### Use Chopsticks for Full Error Logs
143+
144+
For deeper analysis:
136145

137-
### View Nested Errors
146+
* Use Chopsticks to **replay the message with logging enabled**
147+
* See exactly **which instruction failed**, and why
148+
* View full error chains like `FailedToTransactAsset`, or `AssetNotFound`
138149

139-
Most indexers show the outermost error (e.g., `LocalExecutionIncompleteWithError`), which is often enough to understand basic failures.
150+
This is especially useful when dealing with:
140151

141-
### Use Chopsticks for Full Logs
152+
* Multi-hop XCMs
153+
* Custom asset locations
154+
* Execution mismatches or weight issues
142155

143-
With logging enabled, Chopsticks will show:
156+
→ For replay setup, see [Replay and Dry Run XCMs Using Chopsticks](/tutorials/interoperability/replay-and-dry-run-xcms/){target=\_blank}.
144157

145-
* Which instruction failed
146-
* Full error chain (e.g., `FailedToTransactAsset`, `AssetNotFound`)
147-
* Precise reason for rollback or halt
158+
#### Recommended Debugging Workflow
148159

149-
→ Useful for understanding weight failures, malformed assets, or execution mismatches.
160+
1. **Start with indexer or API output** to inspect dispatch errors.
161+
2. If unclear, **replay using Chopsticks** to trace message steps.
162+
3. **Inspect logs** to pinpoint the failing instruction and error.
163+
4. Adjust asset location, weight, or execution logic accordingly.
150164

151165
## Step 5: Handle Older Runtimes
152166

0 commit comments

Comments
 (0)