RPC Error Codes¶

When a JSON-RPC call to Bitcoin Core fails, the response contains an error object with a numeric code and a human-readable message. Understanding these error codes helps developers diagnose problems quickly and build robust applications.

Error Response Format¶

A JSON-RPC error response has the following structure:

{
  "result": null,
  "error": {
    "code": <numeric code>,
    "message": "<human-readable description>"
  },
  "id": "<request id>"
}

For example, calling an unknown RPC method:

> bitcoin-cli unknownmethod
error code: -32601
error message:
Method not found

Standard JSON-RPC Errors¶

These errors are defined by the JSON-RPC 2.0 specification and indicate problems with the request itself rather than the application logic.

General Application Errors¶

These errors indicate problems with the data or state passed to RPC calls.

P2P Client Errors¶

These errors relate to the node’s network connectivity and peer management.

Chain Errors¶

Code	Name	Description	Resolution
-33	RPC_CLIENT_MEMPOOL_DISABLED	No mempool instance found.	Ensure the node is not running with `-blocksonly`; mempool is required for transaction relay.

Wallet Errors¶

These errors occur when interacting with wallet-related RPCs.

Block Validation Reject Reasons¶

When submitting blocks or transactions, Bitcoin Core may return an error with a reject reason string. These are not numeric error codes but descriptive messages that appear in the message field of RPC_VERIFY_REJECTED (code -26) or RPC_VERIFY_ERROR (code -25) responses. Below are common reject reasons you may encounter, especially in regtest mode.

Regtest Troubleshooting¶

The following regtest-specific issues are commonly encountered:

``bad-fork-prior-to-checkpoint (code 67)``

This error appears when running generate or generatetoaddress on a regtest chain that has been manually modified or has become inconsistent:

$ bitcoin-cli -regtest generatetoaddress 11 $(bitcoin-cli -regtest getnewaddress)
error code: -25
error message:
CreateNewBlock: TestBlockValidity failed: bad-fork-prior-to-checkpoint (code 67)

Resolution: Delete the regtest subdirectory and restart:

$ bitcoin-cli -regtest stop
$ rm -rf ~/.bitcoin/regtest
$ bitcoind -regtest -daemon

``generate`` command not found

The generate RPC was removed in Bitcoin Core 18.0. Use generatetoaddress instead:

## Bitcoin Core 18.0+
$ bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)

Wallet not found in regtest

Wallets must be created or loaded explicitly in newer versions:

$ bitcoin-cli -regtest createwallet "test"
$ bitcoin-cli -regtest loadwallet "test"

Insufficient funds in regtest

Generate at least 101 blocks to make coinbase rewards spendable:

$ bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)

Table Of Contents

Previous topic

Next topic

Contribute