問題排查
當錢包連線、登入認證或交易簽署失敗時,可依下表的錯誤碼或典型現象快速排查並修復。
向使用者顯示清楚的錯誤訊息
Section titled “向使用者顯示清楚的錯誤訊息”連接器拋出的例外為 D9ConnectorError,並帶有結構化 code 欄位,建議在介面邊界層統一處理:
import { D9ConnectorError } from "@d9-network/dapp-connector";
export function formatErrorMessage(error: unknown): string { if (error instanceof D9ConnectorError) { switch (error.code) { case "connection_cancelled": case "authentication_cancelled": return "使用者已取消連線。"; case "provider_unavailable": return "未偵測到 D9 錢包提供者,請在 D9 錢包中開啟或使用 WalletConnect 掃碼連線。"; case "request_failed": return `簽署請求遭拒絕或執行失敗: ${error.message}`; default: return `錢包操作異常 (${error.code}): ${error.message}`; } } return "錢包通訊過程中發生未預期的錯誤。";}連接器錯誤碼
Section titled “連接器錯誤碼”| 錯誤碼 | 原因 | 處理方式 |
|---|---|---|
discovery_failed |
偵測 window.injectedWeb3 時發生錯誤 |
切換至 WalletConnect 通道 |
provider_unavailable |
指定使用注入通道但未偵測到 d9-wallet |
提供 WalletConnect QR Code 或行動裝置深連結 |
initialization_failed |
WalletConnect 客戶端初始化失敗 | 檢查瀏覽器 localStorage 權限、網路連線與 Relay 設定 |
connection_failed |
錢包拒絕了工作階段連線請求 | 顯示錯誤並允許使用者重試 |
connection_cancelled |
使用者關閉或取消配對 | 回到閒置狀態,切勿自動重複彈窗 |
request_failed |
負載驗證未通過或使用者拒絕簽署 | 檢查負載格式、目前授權帳戶與請求的 RPC 方法 |
authentication_failed |
Challenge 遭拒或憑證產生失敗 | 向後端重新取得新的 Challenge 後重試 |
authentication_cancelled |
使用者取消登入視窗 | 中止登入流程,不建立後端工作階段 |
invalid_authentication_response |
回傳結果非合法的 CAIP-122 CACAO 憑證 | 檢查 Challenge 欄位格式與後端協定相容性 |
disconnect_failed |
遠端工作階段中斷失敗 | 仍應清除本機前端狀態,並允許重新連線 |
若沒有對應錯誤碼,請依現象排查:
| 現象 | 原因 | 處理方式 |
|---|---|---|
| 偵測不到注入式提供者 | 桌面瀏覽器與一般手機瀏覽器不存在 window.injectedWeb3['d9-wallet'],注入通道僅在 D9 錢包內建瀏覽器中可用 |
改用 transport: "auto" 或 "walletconnect" |
| 錢包已簽署但鏈上無紀錄 | 僅完成簽署,尚未向 RPC 廣播交易 | 使用 polkadot-api 客戶端呼叫 client.submit(signedTx) 廣播(參閱完整交易生命週期) |
報錯 Transaction Rejected: Bad Genesis |
誤將 WalletConnect 協定鏈 ID(d9net:...)當作 genesisHash 填入交易 |
改用 chain_getBlockHash [0] 回傳的真實 32 位元組創世雜湊(見主網端點) |
報錯 Slippage Exceeded 或 Insufficient Balance |
交易打包前池子儲備變動,或帳戶資金受 Holds/Freezes 鎖定 | 以最新最終確認區塊重新讀取儲備並計算滑點下限,核對扣除存活押金與鎖定後的可轉出餘額 |
