From c27098371894a11d45532c33be69f312d250d0f4 Mon Sep 17 00:00:00 2001
From: daushack <55809157+daushack@users.noreply.github.com>
Date: Sat, 16 May 2026 23:07:20 +0800
Subject: [PATCH 1/3] Add regtest block generation troubleshooting notes

---
 examples/testing.rst | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/examples/testing.rst b/examples/testing.rst
index a02076ca..f3dcd296 100644
--- a/examples/testing.rst
+++ b/examples/testing.rst
@@ -36,6 +36,43 @@ Start ``bitcoind`` in regtest mode to create a private block chain.
 
    ## Bitcoin Core 18.0 and later
    bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)
+If block generation fails, the error message normally indicates that the
+regtest node, wallet, or block chain state needs to be prepared before
+continuing:
+
+.. list-table:: Common regtest block generation errors
+   :widths: 30 35 35
+   :header-rows: 1
+
+   * - Error
+     - Likely cause
+     - Suggested resolution
+   * - ``Method not found`` or RPC error ``-32601``
+     - The command uses an RPC that is not available in the Bitcoin Core
+       version you are running. For example, ``generate`` was available in
+       older releases, while newer releases use ``generatetoaddress``.
+     - Use the command shown above for your Bitcoin Core version, or run
+       ``bitcoin-cli -regtest help generatetoaddress`` to confirm the
+       supported syntax.
+   * - ``Invalid address or key`` or RPC error ``-5``
+     - The address passed to ``generatetoaddress`` is missing, malformed, or
+       for a different network.
+     - Create a regtest address with ``bitcoin-cli -regtest getnewaddress``
+       and pass that address to ``generatetoaddress``.
+   * - ``Requested wallet does not exist or is not loaded`` or RPC error
+       ``-18``
+     - The node was started without an available wallet, so
+       ``getnewaddress`` cannot return an address.
+     - Create or load a wallet first, for example
+       ``bitcoin-cli -regtest createwallet testwallet``, then request a new
+       address again.
+   * - ``TestBlockValidity failed: bad-fork-prior-to-checkpoint`` or RPC
+       error ``67``
+     - The local regtest chainstate was created with incompatible consensus
+       parameters or an older Bitcoin Core release.
+     - Stop the node, remove only the ``regtest`` subdirectory from the
+       Bitcoin Core data directory, restart in regtest mode, and generate the
+       blocks again. Back up any wallets before deleting data.
 
 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.
 

From 272d6f118b5163201d7465c9783f136132ac4c89 Mon Sep 17 00:00:00 2001
From: daushack <55809157+daushack@users.noreply.github.com>
Date: Sat, 16 May 2026 23:12:24 +0800
Subject: [PATCH 2/3] Fix regtest troubleshooting spacing

---
 examples/testing.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/examples/testing.rst b/examples/testing.rst
index f3dcd296..d4c68973 100644
--- a/examples/testing.rst
+++ b/examples/testing.rst
@@ -35,7 +35,8 @@ Start ``bitcoind`` in regtest mode to create a private block chain.
    bitcoin-cli -regtest generate 101
 
    ## Bitcoin Core 18.0 and later
-   bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)
+  bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)
+
 If block generation fails, the error message normally indicates that the
 regtest node, wallet, or block chain state needs to be prepared before
 continuing:

From ea8cd713edab38e931c3395133a08104a55d9806 Mon Sep 17 00:00:00 2001
From: daushack <55809157+daushack@users.noreply.github.com>
Date: Sat, 16 May 2026 23:17:33 +0800
Subject: [PATCH 3/3] Fix regtest command indentation

---
 examples/testing.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/testing.rst b/examples/testing.rst
index d4c68973..74f16fa9 100644
--- a/examples/testing.rst
+++ b/examples/testing.rst
@@ -35,7 +35,7 @@ Start ``bitcoind`` in regtest mode to create a private block chain.
    bitcoin-cli -regtest generate 101
 
    ## Bitcoin Core 18.0 and later
-  bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)
+   bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)
 
 If block generation fails, the error message normally indicates that the
 regtest node, wallet, or block chain state needs to be prepared before