# Error codes

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

The errors a BSV blockchain wallet returns through the BRC-100 interface, what each one means and what to check, from @bsv/sdk and @bsv/wallet-toolbox.

import BlueTable from '/snippets/BlueTable.jsx';

Find the cause of a wallet error by its name or the start of its message. Every call your app makes through the BRC-100 (BRC-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 substrate (The 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:

<BlueTable>

| 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 |

</BlueTable>

### 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:

```bash
npm install @bsv/sdk
```

This helper checks both:

```javascript
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`:

<BlueTable>

| 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 HMAC (Hash 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 |

</BlueTable>

## WERR errors

An error that both packages define, such as `WERR_INSUFFICIENT_FUNDS`, has the same name and message in each.

### Arguments and requests

<BlueTable nowrapFirst>

| 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 UTXOs (Unspent transaction output) that fund the wallet changed while it planned the action, as [How the toolbox tracks UTXOs](https://bsvblockchain.com/docs/wallet-dev/wallet-toolbox/utxo-lifecycle/) 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 |

</BlueTable>

### Funds and broadcast

<BlueTable nowrapFirst>

| 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 satoshis (The 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](https://bsvblockchain.com/docs/guides/go-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 tracker (A service that checks a merkle root against the block headers of the network) did not accept the merkle root (One 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 |

</BlueTable>

The `status` of an entry in `reviewActionResults` says what happened to that transaction:

<BlueTable nowrapFirst>

| 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 |

</BlueTable>

For an operation that sends a transaction to an overlay service (Built 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

<BlueTable nowrapFirst>

| 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](https://bsvblockchain.com/docs/wallet-dev/wallet-toolbox/storage-adapter/) 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 batch (A 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 |

</BlueTable>

### Authorization

<BlueTable nowrapFirst>

| 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 |

</BlueTable>

### Errors inside the wallet

<BlueTable nowrapFirst>

| 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 |

</BlueTable>

## 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`:

<BlueTable>

| 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](https://bsvblockchain.com/docs/get-started/quick-start-browser/#troubleshooting) |
| `HTTPWalletJSON: originator is required when using the HTTP substrate in Node.js.` | A Node script reached the HTTP substrate without an originator (The 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'` |

</BlueTable>

### `@bsv/simple`

`@bsv/simple` 0.7.2 throws these errors. Most of its methods add a prefix to the error they catch:

<BlueTable>

| 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](https://bsvblockchain.com/docs/get-started/quick-start-browser/#troubleshooting) |
| `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 |

</BlueTable>

## Broadcast errors

BSV Broadcaster reports the status of a transaction, not a wallet error. Its statuses are listed in [Broadcast transactions with BSV Broadcaster](https://bsvblockchain.com/docs/guides/services/broadcasting/#statuses).

## Related articles

To learn more about wallet calls and how the wallet tracks outputs on the BSV blockchain, review these articles:

- [Wallet API (BRC-100)](https://bsvblockchain.com/docs/reference/wallet-api/)
- [How the toolbox tracks UTXOs](https://bsvblockchain.com/docs/wallet-dev/wallet-toolbox/utxo-lifecycle/)