Browser Extension

Testing and Troubleshooting

Develop against Testnet and Devnet, run locally, and fix common errors.

Testing on Testnet or Devnet

  1. In Joey, open Settings → Network and choose Testnet (or Devnet).
  2. Fund your test address from an XRPL faucet.
  3. Pass chain: 'xrpl:1' (or 'xrpl:2') on signing calls. If the wallet is still on Mainnet, the request fails with 4901 instead of signing on the wrong network.

There's no method to switch networks from a dApp. Ask the user to switch in Joey, and listen for networkChanged.

Don't set NetworkID on transactions; Joey refuses it on every network it supports.

Local development

  • http://localhost, http://127.0.0.1 and http://[::1] can connect on any port. Every other site must use https:.
  • file:// pages can't connect. Serve your dApp from a development server.

Troubleshooting

Symptom Likely cause
waitForJoey rejects with 4900 Joey isn't installed or is disabled; the page is a file:// page; or you're in a sandboxed iframe.
connect({ silent: true }) returns [] Expected until the user approves your site. Call connect() from a button click.
getNetwork() throws 4100 Your site isn't connected yet. Connect first, or read chain from the connect result.
Signing throws 4100 "transaction type not permitted" The transaction, or an inner Batch transaction, is a refused type or flag.
Signing throws -32602 Account isn't the signing account; fee over 2 XRP with autofill: false; a NetworkID field; an X-address; or malformed fields.
Signing throws 4901 Your chain doesn't match Joey's network, or the user switched network during the request.
-32005 Too many concurrent or pending requests, or the user rejected many requests in a row. Back off.
A call stays pending for minutes It's waiting for the user to approve (up to 5 minutes) or to unlock Joey. Don't time out sooner.
Sign-in "signature did not verify" You didn't check isChallengeSignIn: Ledger accounts return signedTx, not signature.
signTransactionFor signature rejected by the network This method never autofills. Set Fee, Sequence and LastLedgerSequence yourself.
Batch refused with 4100 The extension doesn't support Batch yet (check joey.supportsBatch()), or an inner transaction is refused.
Batch refused with -32602 A batch involving other accounts with autofill on; invalid inner fields; more than one transaction in the request; or a Ledger account.
instanceof JoeyRpcError is false Two copies of the SDK are bundled. Deduplicate @joeywallet/wallet-sdk.
"useJoey must be used inside a JoeyProvider" Wrap your tree in <JoeyProvider>. In Next.js, do it inside a 'use client' component.
PreviousGemWallet CompatibilityNext Quick Start