Skip to content

Errors

The wallet's errors live in kaspa.exceptions. Most are self-explanatory; a few are common enough that they're worth knowing ahead of time. The full list is in kaspa.exceptions.

Common errors

Error Triggered by Fix
WalletAlreadyExistsError wallet_create(filename=..., overwrite_wallet_storage=False) when the file exists. Catch and call wallet_open(...) instead, or pass overwrite_wallet_storage=True (clobbers). See Lifecycle → create-or-open.
WalletNotOpenError Any prv_key_data_*, accounts_*, transactions_* call before wallet_create / wallet_open. Open the wallet first.
WalletNotConnectedError accounts_activate(...) without a connected wRPC client. await wallet.connect(...) first.
WalletNotSyncedError accounts_send, accounts_estimate, accounts_get_utxos, accounts_transfer before the processor finishes its sync handshake. Wait on wallet.is_synced (poll or SyncState listener) — see Sync State.
WalletInsufficientFundsError accounts_send / accounts_transfer when the mature balance can't cover outputs + fees. Wait for pending UTXOs to mature (Maturity event), reduce amount, or lower priority fee.
"Invalid prv key data kind, supported types are Mnemonic and SecretKey" prv_key_data_create(kind=PrvKeyDataVariantKind.Bip39Seed) or kind=ExtendedPrivateKey. Use Mnemonic or SecretKey. The other two enum variants are not implemented upstream — see Private Keys.
UtxoIndexNotEnabled (event, not exception) Connecting to a kaspad without the UTXO index. The processor refuses to proceed. Point at a node that has UTXO indexing enabled.
RuntimeError: cannot change network while connected wallet.set_network_id(...) after connect(). await wallet.disconnect() → set_network_id(...) → await wallet.connect().
RuntimeError: cannot derive address on a keypair account accounts_create_new_address(...) on a keypair account. Keypair accounts have one fixed address; read it from descriptor.receive_address. See Keypair accounts.

Where to next