Add regtest block generation troubleshooting

examples/testing.rst

@@ -50,4 +50,39 @@ 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``.
 
+Troubleshooting Block Generation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If block generation fails, first check that both ``bitcoind`` and
+``bitcoin-cli`` are using the same network option.  Commands used in this
+example should include ``-regtest`` and should use a regtest address from the
+same node or wallet.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Error
+     - Resolution
+   * - ``error code: -32601`` or ``Method not found`` when calling
+       ``setgenerate`` or ``generate``
+     - The RPC is not available in your Bitcoin Core version.  Use the command
+       shown above for your version; for Bitcoin Core 18.0 and later, mine with
+       ``generatetoaddress``.
+   * - ``No wallet is loaded`` when calling ``getnewaddress``
+     - Create or load a regtest wallet before requesting an address.  For
+       example, run ``bitcoin-cli -regtest createwallet "regtest"`` and then
+       use ``bitcoin-cli -regtest -rpcwallet=regtest getnewaddress``.
+   * - ``Invalid address`` or ``Invalid Bitcoin address`` when calling
+       ``generatetoaddress``
+     - Use an address generated by the same regtest node.  Mainnet and testnet
+       addresses are for different networks and are rejected in regtest mode.
+   * - ``CreateNewBlock: TestBlockValidity failed:
+       bad-fork-prior-to-checkpoint (code 67)``
+     - This indicates that the candidate block would fork before a checkpoint,
+       which should not happen on a clean regtest chain.  Confirm that both the
+       daemon and CLI are using ``-regtest``.  If they are, stop the node and
+       start from a fresh regtest chain by deleting only the ``regtest``
+       subdirectory or by using a new ``-datadir``.
+
 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.)