Skip to content

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.

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.";
}
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

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