Troubleshooting
Use this reference when a wallet connection, sign-in, or transaction call fails. Look up the error code or symptom and apply the corresponding resolution.
Display actionable error messages
Section titled “Display actionable error messages”The connector throws D9ConnectorError with a structured code. Handle it at your UI boundary:
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 "Connection was cancelled by the user."; case "provider_unavailable": return "No D9 wallet provider found. Please open in D9 Wallet or scan with WalletConnect."; case "request_failed": return `Signing request was rejected or failed: ${error.message}`; default: return `Wallet operation error (${error.code}): ${error.message}`; } } return "An unexpected error occurred during wallet communication.";}Connector error codes
Section titled “Connector error codes”| Code | Cause | Resolution |
|---|---|---|
discovery_failed |
Failed to inspect window.injectedWeb3 |
Fall back to WalletConnect |
provider_unavailable |
Injected transport requested, but d9-wallet is absent |
Offer a WalletConnect QR code or deep link |
initialization_failed |
WalletConnect client failed to initialize | Check browser localStorage access, network connectivity, and relay configuration |
connection_failed |
Wallet rejected the session proposal | Surface the error and allow the user to retry |
connection_cancelled |
User dismissed pairing | Return cleanly to idle; do not re-prompt automatically |
request_failed |
Payload failed validation or user rejected signing | Verify payload format, selected account, and supported RPC methods |
authentication_failed |
Challenge was rejected or proof generation failed | Request a fresh backend challenge and retry |
authentication_cancelled |
User dismissed the sign-in prompt | Abort login and create no backend session |
invalid_authentication_response |
Response is not a valid CAIP-122 CACAO proof | Verify challenge schema and backend compatibility |
disconnect_failed |
Remote session teardown failed | Clear local frontend state anyway and allow reconnecting |
Common pitfalls
Section titled “Common pitfalls”No connector error code? Match the symptom below:
| Symptom | Cause | Resolution |
|---|---|---|
| Injected provider not detected | Desktop and standard mobile browsers do not expose window.injectedWeb3['d9-wallet']; injected transport works only inside D9 Wallet’s in-app browser |
Use transport: "auto" or "walletconnect" |
| Signed but never appears on chain | Signature was never broadcast to RPC | Submit the signed extrinsic with client.submit(signedTx) via polkadot-api (see Transaction Lifecycle) |
| “Transaction Rejected: Bad Genesis” | WalletConnect protocol chain ID (d9net:...) was passed as genesisHash |
Pass the real 32-byte genesis hash from chain_getBlockHash [0] (see Mainnet Endpoints) |
| “Slippage Exceeded” / “Insufficient Balance” | Reserves shifted before inclusion, or funds are locked by holds/freezes | Re-read pool reserves at the latest finalized block, recompute slippage bounds, and verify transferable balance after existential deposit and locks |
