Error codes
Find the cause of a wallet error by its name or the start of its message. Every call your app makes through the BRC-100BRC-100: the standard interface between a wallet and an app wallet interface, such as createAction or signAction, can fail with one of the WERR_* errors below or with one of the plain errors listed after them. The WERR_* errors come from @bsv/sdk and @bsv/wallet-toolbox.
This page was written against @bsv/sdk 4.0.1 and @bsv/wallet-toolbox 2.15.2.
How a wallet error reaches your app
Every WERR_* error carries isError: true, a name and a message. What else your app receives depends on the substrateThe channel WalletClient uses to talk to the wallet, such as an injected window object, a local HTTP port or cross-document messages that WalletClient connected through:
| Connection | What your app receives |
|---|---|
A Wallet from @bsv/wallet-toolbox in your own process | The toolbox error class. Its code returns the same string as name, such as 'WERR_INVALID_PARAMETER' |
HTTP JSON (json-api on port 3321, secure-json-api on port 2121) | WERR_REVIEW_ACTIONS, WERR_INVALID_PARAMETER and WERR_INSUFFICIENT_FUNDS rebuilt as @bsv/sdk classes with a numeric code (5, 6, 7). @bsv/sdk rebuilds an error only from an HTTP 400 answer whose body has isError and an integer code. The toolbox puts a code only in these three errors and in WERR_INVALID_MERKLE_ROOT (8), so any other toolbox error arrives as Invalid wallet error envelope. Code 5 from internalizeAction becomes Invalid internalizeAction wallet error code. Any other answer becomes HTTPWalletJSON <call> failed with HTTP status <status> |
Wallet wire (Cicada), cross-document messages (XDM) and React Native | A WalletError whose name is WalletError, with a numeric code. Only codes 2 to 8 keep the wallet’s message. Any other error becomes code 1 with the message Wallet operation failed. A toolbox error has a string code, so behind the wire it arrives as code 1 and loses its name and message. Over the wire, code 8 from abortAction returns { aborted: false } instead of an error |
window.CWI | Whatever the wallet throws, unchanged |
Catch a wallet error
Check name or the numeric code, not instanceof. @bsv/sdk and @bsv/wallet-toolbox each define their own class for the same error name, and the @bsv/sdk WERR_* classes do not extend WalletError, so instanceof matches only the class of the package that built the error. The numeric codes are exported from @bsv/sdk as walletErrors. Install the package if your app does not have it yet:
npm install @bsv/sdkThis helper checks both:
import { walletErrors } from '@bsv/sdk'
function isInsufficientFunds (err) {
return err?.name === 'WERR_INSUFFICIENT_FUNDS' || err?.code === walletErrors.insufficientFunds
}Checking both covers the toolbox error, whose code is a string, and an error that arrives over the wire with only its numeric code. For an @bsv/sdk error, rely on code, because its name comes from the class name, which a minified bundle can change.
Numeric codes
These are the values of walletErrors in @bsv/sdk:
| Name | Code | Meaning |
|---|---|---|
unknownError | 1 | Any error without one of the codes below |
unsupportedAction | 2 | The wallet does not support the call |
invalidHmac | 3 | An HMACHash based message authentication code did not verify |
invalidSignature | 4 | A signature did not verify |
reviewActions | 5 | Same as WERR_REVIEW_ACTIONS |
invalidParameter | 6 | Same as WERR_INVALID_PARAMETER |
insufficientFunds | 7 | Same as WERR_INSUFFICIENT_FUNDS |
abortRefused | 8 | The wallet refused to abort the action because it has already been broadcast |
WERR errors
An error that both packages define, such as WERR_INSUFFICIENT_FUNDS, has the same name and message in each.
Arguments and requests
| Error | Message | Cause and what to do |
|---|---|---|
WERR_INVALID_PARAMETER | The <parameter> parameter must be <requirement> | An argument of the call does not meet its rule. @bsv/sdk checks the arguments in WalletClient before the call leaves your app, for example The description parameter must be at least 5 length. Fix the argument that the parameter field names |
WERR_MISSING_PARAMETER | The required <parameter> parameter is missing. | A required value was not given. The parameter field names it. Supply that value |
WERR_BAD_REQUEST | The request is invalid. or a specific message | The toolbox refused the request, for example task <name> has already been added. when a monitor task is added twice |
WERR_INVALID_PUBLIC_KEY | The provided public key "<key>" is invalid or malformed. or the same without the key | A public key in the request could not be read. The toolbox rebuilds this error from the answer of a remote storage server and does not throw it itself. The message holds the key only on Mainnet. The key field always holds the key that failed. Check that your app passed a valid public key |
WERR_INVALID_OPERATION | An invalid operation was requested. or a specific message | The wallet cannot do what was asked in its current state. With the message wallet funding changed repeatedly during action planning; retry createAction, call createAction again. The UTXOsUnspent transaction output that fund the wallet changed while it planned the action, as How the toolbox tracks UTXOs explains |
WERR_NOT_IMPLEMENTED | Not implemented. or a specific message | The wallet does not support this call or option. With recovery of out-of-session signAction reference data is not yet implemented., the wallet no longer holds the reference that createAction returned, so call signAction on the same wallet instance that created the action |
Funds and broadcast
| Error | Message | Cause and what to do |
|---|---|---|
WERR_INSUFFICIENT_FUNDS | Insufficient funds in the available inputs to cover the cost of the required outputs… | The wallet cannot pay the outputs and the fee. The message goes on with (<more> more satoshis are needed, for a total of <total>). The moreSatoshisNeeded and totalSatoshisNeeded fields hold the two amounts in satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV. Fund the wallet on the network your app uses with at least moreSatoshisNeeded, plus some margin for the fee of the extra inputs. The guide to moving your app to Mainnet covers this error on a wallet that is on the wrong network |
WERR_REVIEW_ACTIONS | Undelayed createAction or signAction results require review. | createAction or signAction ran with acceptDelayedBroadcast: false, and the broadcast did not succeed. The toolbox also throws it from internalizeAction. Read the status of each entry in reviewActionResults, described below. The txid, tx, sendWithResults and noSendChange fields match the result the call would have returned |
WERR_BROADCAST_UNAVAILABLE | Unable to broadcast transaction at this time. | The transaction could not be broadcast. The toolbox rebuilds this error from the answer of a remote storage server and does not throw it itself. The message says the failure is temporary, so try again later |
WERR_INVALID_MERKLE_ROOT | Invalid merkleRoot <root> for block <hash> at height <height> for txid <txid>. | A chain trackerA service that checks a merkle root against the block headers of the network did not accept the merkle rootOne hash that stands for all the transactions in a block of a stored proof. The toolbox throws it while it builds the proof data for a transaction. Check which chain tracker the wallet uses, and the blockHash, blockHeight and txid fields |
The status of an entry in reviewActionResults says what happened to that transaction:
| Status | Meaning |
|---|---|
success | The network accepted the transaction |
doubleSpend | Another transaction already spends one of its inputs and wins by the first seen rule. competingTxs lists the competing transaction IDs and competingBeef holds their data. The txid is empty when the wallet found the conflict before it built the transaction |
invalidTx | The network rejected it as an invalid transaction |
serviceError | The broadcast services cannot reach the network. The wallet queues the transaction and retries it later |
For an operation that sends a transaction to an overlay serviceBuilt from topic managers, which decide what is admitted, and lookup services, which query what was admitted., @bsv/sdk exports withDoubleSpendRetry. It retries only when the operation throws the @bsv/sdk class WERR_REVIEW_ACTIONS with a doubleSpend entry, such as the error that HTTP JSON rebuilds. The toolbox class and a WalletError from the wire are thrown again with no retry. Before each retry it sends every competing transaction to the broadcaster you give it. It runs the operation up to 5 times by default, and you can set up to 100.
Storage and sync
| Error | Message | Cause and what to do |
|---|---|---|
WERR_NOT_ACTIVE | WalletStorageManager is not accessing user's active storage… or a specific message | The call needs the active storage of the user, and the wallet is not writing to it or has conflicting active stores. See Plug in your own storage for the fix with setActive |
WERR_NETWORK_CHAIN | Configured network chain is invalid or does not match across services. | WalletStorageManager.syncToWriter or syncFromReader found that the two stores are on different chains, and stopped before moving any data. The message names each store and its chain. Sync only stores of the same chain |
WERR_UTXO_REVIEW_INCONCLUSIVE | UTXO review was inconclusive for <unknown> of <checked> candidates… | A review of the wallet’s UTXOs could not get a clear answer for every output, so it changed nothing. The message ends with no outputs were changed. The checked, confirmedSpent and unknown fields hold the counts. Run the review again later |
WERR_ACTION_BATCH_STATE | Action batch cannot continue because it is <state>. | An action batchA storage optimization of the toolbox that groups the work of several actions. The Wallet option actionBatchMode sets it is no longer usable. The state field is one of missing, expired, hard-expired, aborted, committed, inactive or conflicted, and batchId names the batch. The toolbox resumes an expired batch when the storage supports it. For any other state it aborts the batch and stops using it, so a later action does not join it |
Authorization
| Error | Message | Cause and what to do |
|---|---|---|
WERR_UNAUTHORIZED | Access is denied due to an authorization error. or a specific message | An identity or permission check failed. The message says which one, for example identityKey does not match authentication, function may only access authenticated user. or The action reference belongs to a different originator. Check that the request comes from the identity and the app that the message names |
Errors inside the wallet
| Error | Message | Cause and what to do |
|---|---|---|
WERR_INTERNAL | An internal error has occurred. or a specific message | The wallet failed for a reason outside your request. The message is the only detail the error carries |
WERR_UNKNOWN | The original message, or the value that was thrown | The wallet serialized something that was not a wallet error, such as a plain value or an error with no name |
Other errors from WalletClient and the wallet
Some failures are not WERR_* errors. These come from @bsv/sdk and from the permissions manager of @bsv/wallet-toolbox:
| Message | Cause and what to do |
|---|---|
No wallet available over any communication substrate. Install a BSV wallet today! | WalletClient found no wallet on any substrate. See the troubleshooting section of Send a payment from a web app |
HTTPWalletJSON: originator is required when using the HTTP substrate in Node.js. | A Node script reached the HTTP substrate without an originatorThe name of the calling app, the second argument of WalletClient. Pass one as the second argument of WalletClient, such as new WalletClient('auto', 'localhost') |
HTTPWalletJSON <call> failed with HTTP status <status> | The HTTP wallet answered with an error that @bsv/sdk does not rebuild as a WERR_* class, such as code 8, or with a status other than 400 |
Invalid wallet error envelope | The HTTP wallet answered 400 with isError, but with no integer code. A toolbox error other than codes 5 to 8 arrives this way |
Invalid <call> wallet error code | The HTTP wallet sent code 5 for a call other than createAction or signAction, such as internalizeAction |
Wallet operation failed | The wallet sent an error without one of the numeric codes 2 to 8, and the substrate hid its message |
HMAC is not valid or Signature is not valid | verifyHmac or verifySignature of ProtoWallet throws this instead of returning valid: false, with code 'ERR_INVALID_HMAC' or 'ERR_INVALID_SIGNATURE'. The toolbox Wallet does the same for a call without privileged. Over the wire it arrives as Wallet operation failed. Check the data, the protocol, the key ID and the counterparty of the call |
Permission denied. or The user has denied the request for permission. | The user refused a permission request in a wallet that uses the toolbox permissions manager. The error has code 'ERR_PERMISSION_DENIED' |
@bsv/simple
@bsv/simple 0.7.2 throws these errors. Most of its methods add a prefix to the error they catch:
| Message | Cause and what to do |
|---|---|
No wallet available over any communication substrate… | createWallet connects through WalletClient and found no wallet. See the troubleshooting section of Send a payment from a web app |
Topic "<topic>" must start with "tm_" prefix | advertiseSHIP got a topic name without the tm_ prefix. Pass a topic name that starts with tm_ |
Service "<service>" must start with "ls_" prefix | advertiseSLAP got a service name without the ls_ prefix. Pass a service name that starts with ls_ |
Send failed: <message> | send failed. The rest of the message is the original error, such as At least one output is required or the message of a wallet error on this page |
Payment failed: <message> | pay failed. The rest of the message is the original error |
registryUrl is required, after a prefix such as Tag registration failed: | A registry method got no registryUrl, and the defaults passed to createWallet have none. Pass it to the method or set registryUrl in the defaults |
Broadcast errors
BSV Broadcaster reports the status of a transaction, not a wallet error. Its statuses are listed in Broadcast transactions with BSV Broadcaster.
Related articles
To learn more about wallet calls and how the wallet tracks outputs on the BSV blockchain, review these articles: