diff --git a/examples/testing.rst b/examples/testing.rst index a02076ca..ff45b62c 100644 --- a/examples/testing.rst +++ b/examples/testing.rst @@ -51,3 +51,62 @@ Verify that we now have 50 bitcoins available to spend. You can now use Bitcoin Core `RPCs <../reference/rpc/index.html>`__ prefixed with ``bitcoin-cli -regtest``. Regtest wallets and block chain state (chainstate) are saved in the ``regtest`` subdirectory of the Bitcoin Core configuration directory. You can safely delete the ``regtest`` subdirectory and restart Bitcoin Core to start a new regtest. (See the `Developer Examples Introduction <../examples/index.html>`__ for default configuration directory locations on various operating systems. Always back up mainnet wallets before performing dangerous operations such as deleting.) + +Error Codes +^^^^^^^^^^^ + +When Bitcoin Core commands fail, they return error messages that include both a human-readable description and a numeric error code. Understanding these error codes helps you debug issues during development. + +**Format:** Error messages are returned as JSON-RPC responses with the format: + +:: + + { + "result": null, + "error": { + "code": -XX, + "message": "Description" + } + } + +**Common Regtest Error Codes:** + +**Block Generation Errors:** + +``bitcoin-cli -regtest generate 11`` — When generating blocks, you may encounter validation errors if block chain rules are violated: + +:: + + CreateNewBlock: TestBlockValidity failed: bad-fork-prior-to-checkpoint (code 67) + +This error occurs when attempting to create a block that violates consensus rules, such as creating a fork before a checkpoint height. In regtest mode, checkpoints are disabled by default, but other validation rules (such as coinbase maturity—spending transactions must wait 100 blocks) still apply. + +To avoid this error, ensure your block generation follows regtest rules: + +* The first 150 blocks pay a block reward of 50 bitcoins +* Coinbase transactions cannot be spent until 100 blocks after creation (maturity requirement) +* Do not attempt to generate blocks on a forked chain after switching to a newer height + +**Example: Generating Blocks After Coinbase Maturity:** + +:: + + ## Bitcoin Core 18.0 and later + bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress) + ## Wait 100 blocks for coinbase to mature (already satisfied in the 101 block generation above) + + ## Now subsequent block generation will work + bitcoin-cli -regtest generatetoaddress 1 $(bitcoin-cli -regtest getnewaddress) + +**RPC Error Codes Reference:** + +- **-1** — Generic RPC error (e.g., unexpected exceptions) +- **-3** — Type mismatch error (argument wrong type) +- **-5** — Invalid address or key +- **-8** — Block height out of range +- **-10** — Bitcoin Core is shutting down +- **-32601** — Method not found +- **-32602** — Invalid method parameters +- **-32603** — Internal error + +For a complete list of RPC error codes, see the `JSON-RPC error codes `__ reference.