From 2b61556f9047dc31ca344916a31f6ef355f7d806 Mon Sep 17 00:00:00 2001 From: Hendrik <48210159+SirBughunter@users.noreply.github.com> Date: Thu, 14 May 2026 04:36:04 +0200 Subject: [PATCH] Add regtest block generation troubleshooting Document common regtest block generation failures and practical recovery steps near the developer testing example. Refs bitcoin-dot-org/Bitcoin.org#1837 Co-authored-by: Codex --- examples/testing.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/examples/testing.rst b/examples/testing.rst index a02076ca..3f15e3d4 100644 --- a/examples/testing.rst +++ b/examples/testing.rst @@ -39,6 +39,40 @@ Start ``bitcoind`` in regtest mode to create a private block chain. Generate 101 blocks using a special `RPC <../reference/rpc/index.html>`__ which is only available in regtest mode. This takes less than a second on a generic PC. Because this is a new block chain using Bitcoin’s default rules, the first blocks pay a block reward of 50 bitcoins. Unlike mainnet, in regtest mode only the first 150 blocks pay a reward of 50 bitcoins. However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. +Regtest block generation errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Regtest chains are private and disposable, so the safest fix for many +experiments is to stop ``bitcoind`` and restart with a new regtest data +directory. Always make sure you are moving or deleting only the ``regtest`` +subdirectory of your Bitcoin Core configuration directory, never your mainnet +wallet or chainstate. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Error + - Suggested resolution + * - ``Method not found`` when calling ``generate`` + - Use ``generatetoaddress`` with Bitcoin Core 18.0 and later: + ``bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)``. + * - ``getnewaddress`` reports that no wallet is loaded + - Load or create a regtest wallet before using command substitution, for + example ``bitcoin-cli -regtest createwallet ""``. If your node was + built without wallet support, replace the command substitution with any + valid regtest address from another wallet. + * - ``CreateNewBlock: TestBlockValidity failed: + bad-fork-prior-to-checkpoint (code 67)`` + - This is a block verification failure. It is commonly caused by + reusing an old regtest chain after changing Bitcoin Core versions or + consensus-related settings. Stop the node, move the ``regtest`` + subdirectory aside, restart ``bitcoind -regtest -daemon``, and mine + again on the fresh private chain. + * - Newly mined coins do not appear spendable + - Coinbase rewards must mature for 100 confirmations. Generate at least + 101 blocks before trying to spend the first reward. + .. highlight:: bash ::