跳到內容

問題排查

當錢包連線、登入認證或交易簽署失敗時,可依下表的錯誤碼或典型現象快速排查並修復。

連接器拋出的例外為 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 "錢包通訊過程中發生未預期的錯誤。";
}
錯誤碼 原因 處理方式
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 鎖定 以最新最終確認區塊重新讀取儲備並計算滑點下限,核對扣除存活押金與鎖定後的可轉出餘額