跳转到内容

问题排查

当钱包连接、登录认证或交易签名失败时,可根据下表的错误码或典型症状快速定位并修复。

连接器抛出的异常为 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 二维码或移动端深链接
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 锁定 基于最新最终确认区块重新读取储备并计算滑点下限,核对扣除存活押金与锁定后的可转出余额