问题排查
当钱包连接、登录认证或交易签名失败时,可根据下表的错误码或典型症状快速定位并修复。
向用户展示清晰的错误提示
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 二维码或移动端深链接 |
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 锁定 | 基于最新最终确认区块重新读取储备并计算滑点下限,核对扣除存活押金与锁定后的可转出余额 |
