From cd27535dbb3527e3090698af29faef3dca19312b Mon Sep 17 00:00:00 2001 From: Alexandra Tran <12214231+alexandratran@users.noreply.github.com> Date: Thu, 15 Sep 2022 14:04:11 -0700 Subject: [PATCH] Distribute troubleshooting content (#1170) * Distribute troubleshooting content Signed-off-by: Alexandra Tran * fix image path Signed-off-by: Alexandra Tran * remove extra line Signed-off-by: Alexandra Tran Signed-off-by: Alexandra Tran --- .../how-to/troubleshoot/troubleshooting.md | 200 ------------------ .../get-started/install/run-docker-image.md | 21 +- .../how-to/configure/consensus/ibft.md | 25 ++- .../how-to/configure/consensus/qbft.md | 25 ++- .../private-networks/reference/cli/options.md | 6 + .../get-started/install/run-docker-image.md | 21 +- .../how-to/connect/manage-peers.md | 12 ++ .../how-to/connect/sync-node.md | 34 ++- .../how-to/use-besu-api/index.md | 4 +- docs/public-networks/how-to/use-pow/mining.md | 44 +++- docs/public-networks/reference/cli/options.md | 6 + .../reference/genesis-items.md | 18 +- mkdocs.navigation.yml | 2 +- 13 files changed, 191 insertions(+), 227 deletions(-) delete mode 100644 docs/global/how-to/troubleshoot/troubleshooting.md diff --git a/docs/global/how-to/troubleshoot/troubleshooting.md b/docs/global/how-to/troubleshoot/troubleshooting.md deleted file mode 100644 index 992169ec..00000000 --- a/docs/global/how-to/troubleshoot/troubleshooting.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -description: Frequently asked questions and answers for troubleshooting Hyperledger Besu ---- - -# Troubleshooting - -If Hyperledger Besu is not working as expected, here are some things to check or try. - -## Supplied genesis block does not match stored chain data - -If a `Supplied genesis block does not match stored chain data` error occurs, use the genesis file -matching the genesis block of the data directory, or use the -[`--data-path`](../../../public-networks/reference/cli/options.md#data-path) option to specify a different data -directory. - -## Invalid block header - -If a `TimeStampMoreRecentThanParent | Invalid block header` error occurs, the [genesis file](../../../public-networks/concepts/genesis-file.md) of the new node is specifying a higher -[`blockperiodseconds`](../../../private-networks/how-to/configure/consensus/ibft.md#block-time) than the imported chain. -The imported chain makes new blocks faster than the genesis file allows and Besu rejects them with this error. -This error most often occurs when importing chains from older versions of Besu. - -To correct this error, decrease the `blockperiodseconds` in the new [IBFT 2.0 genesis file](../../../private-networks/how-to/configure/consensus/ibft.md#genesis-file) -or [QFBT genesis file](../../../private-networks/how-to/configure/consensus/qbft.md#genesis-file) to a lower value that satisfies the block header validation. - -!!! example - - If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp 1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`, - decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain. - -After you have updated the new genesis file, if the imported chain has a `blockperiodseconds` value set lower than you prefer, you can adjust it by configuring the block time on an -[existing IBFT 2.0](../../../private-networks/how-to/configure/consensus/ibft.md#configure-block-time-on-an-existing-network-deployment) -or [existing QBFT](../../../private-networks/how-to/configure/consensus/qbft.md#configure-block-time-on-an-existing-network) network. - -## Host not authorized - -If a `Host not authorized` error occurs when attempting to access the JSON-RPC API, ensure -[`--host-allowlist`](../../../public-networks/reference/cli/options.md#host-allowlist) includes the host you are -sending the RPC from, or `*`. - -## Peers fail to connect - -If nodes are not communicating, ensure the -[required ports are open](../../../public-networks/how-to/connect/configure-ports.md). - -If your nodes are running in AWS, check you have appropriate `SecurityGroups` to allow access to -the required ports. - -Check that the [enode URLs](../../../public-networks/concepts/node-keys.md#enode-url) specified for -[bootnodes](../../../private-networks/how-to/configure/bootnodes.md) or -[static nodes](../../../public-networks/how-to/connect/static-nodes.md) match the enode URLs displayed when starting the -remote nodes. - -## Mining - -Check block creation. On mining nodes, log messages indicate block creation. - -```bash -2019-05-08 20:28:27.026+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=660, Round=0}, hash=0x759afaba4e923d89175d850ceca4b8ef81f7d9c727b0b0b8e714b624a4b8e8cc -2019-05-08 20:28:29.020+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=661, Round=0}, hash=0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14 -``` - -On non-mining nodes, log messages indicate importing blocks. - -```bash -2019-05-08 20:28:29.026+10:00 | EthScheduler-Workers-1 | INFO | BlockPropagationManager | Imported #661 / 0 tx / 0 om / 0 (0.0%) gas / (0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14) in 0.000s. -2019-05-08 20:28:31.031+10:00 | EthScheduler-Workers-0 | INFO | BlockPropagationManager | Imported #662 / 0 tx / 0 om / 0 (0.0%) gas / (0x0ead4e20123d3f1433d8dec894fcce386da4049819b24b309963ce7a8a0fcf03) in 0.000s. -``` - -To confirm the block number is increasing, use the -[`eth_blockNumber`](../../../public-networks/reference/api/index.md#eth_blocknumber) JSON-RPC API method. - -If there is no block creating in [Clique](../../../private-networks/how-to/configure/consensus/clique.md#extra-data) -or [IBFT 2.0](../../../private-networks/how-to/configure/consensus/ibft.md#extra-data) networks, ensure the validator -addresses in the genesis file match running nodes. - -## Transactions are not mined - -If you add a transaction to the -[transaction pool](../../../public-networks/concepts/transactions/pool.md) and the transaction hash -returns, but the transaction is never mined, check the -[`--min-gas-price`](../../../public-networks/reference/cli/options.md#min-gas-price) option on mining nodes. If the -`gasPrice` on a [transaction](../../../public-networks/how-to/send-transactions.md) is lower than the -`min-gas-price` for the mining node, the transaction will never mine. - -In [free gas networks](../../../private-networks/how-to/configure/free-gas.md), you must set -[`--min-gas-price`](../../../public-networks/reference/cli/options.md#min-gas-price) to zero. - -## Genesis milestone - -Not including a milestone far enough in advance in the genesis file can lead to unexpected and -inconsistent behavior without specific errors. Ensure you include a milestone that is far enough in -advance in the genesis file (for example, `constantinoplefixblock`). - -## Command line options - -Characters such as smart quotes and long (em) hyphens do not work in Besu command line options. -Ensure quotes are not automatically converted to smart quotes, or double hyphens combined into em -hyphens. - -## Logging - -Restart Besu with the command line option -[`--logging=TRACE`](../../../public-networks/reference/cli/options.md#logging) and look at the log files. - -## Pending State Nodes not decreasing for a full node in Grafana - -During [fast synchronization](../../../public-networks/how-to/connect/sync-node.md#run-a-full-node) for a full node, the -Pending State Nodes count is the number of nodes yet to be downloaded, and it should change -constantly. Pending State Nodes trend to 0 during fast synchronization and then goes to 0. - -If the number stays constant, this could mean your node is not syncing against any peers. - -In the following example the Pivot Block is 0 (zero) and the Pending State Nodes value is constant. -This means the node isn't syncing against any peers. The fact that state nodes have been downloaded -means at some stage it was syncing. - -![Fast synchronization](../../../assets/images/fastsync.png) - -The easiest solution in this scenario is to restart fast synchronization to obtain a new -pivot block. - -## Homebrew repair - -When upgrading Besu, you might get the following error: - -```bash -Error: Some taps failed to update! -The following taps can not read their remote branches: - hyperledger/besu -This is happening because the remote branch was renamed or deleted. -Reset taps to point to the correct remote branches by running `brew tap --repair` -``` - -This error is caused by the branch name being updated from `master` to `main` but a reference to `master` still remains. -To fix the branch reference and repair Homebrew, use the command `brew tap --repair`. - -## Thread blocked due to lack of entropy in the system random number generator - -If a thread is reported as blocked, and the top of the stack contains -`sun.security.provider.NativePRNG$RandomIO.readFully` as in the following example, then the operating -system is out of entropy. - -```bash -2021-11-06 11:28:05.971+00:00 | vertx-blocked-thread-checker | WARN | BlockedThreadChecker | Thread Thread[vert.x-worker-thread-2,5,main]=Thread[vert.x-worker-thread-2,5,main] has been blocked for 60387 ms, time limit is 60000 ms -io.vertx.core.VertxException: Thread blocked - at java.base@11.0.11/java.io.FileInputStream.readBytes(Native Method) - at java.base@11.0.11/java.io.FileInputStream.read(FileInputStream.java:279) - at java.base@11.0.11/java.io.FilterInputStream.read(FilterInputStream.java:133) - at java.base@11.0.11/sun.security.provider.NativePRNG$RandomIO.readFully(NativePRNG.java:424) - at java.base@11.0.11/sun.security.provider.NativePRNG$RandomIO.implGenerateSeed(NativePRNG.java:441) - at java.base@11.0.11/sun.security.provider.NativePRNG.engineGenerateSeed(NativePRNG.java:226) - ... -``` - -If this happens, the Besu node can become unresponsive. - -The occurrence of this problem and the possible solutions are system-dependent. -The issue itself is rare, but would most likely occur: - -* On Linux. -* Using virtual machines without randomness source. -* Early after computer startup. - -The solution to this depends on the situation. -A good starting point is to read about [blocking random number generation in Linux](https://man7.org/linux/man-pages/man4/random.4.html). -A quick, non-persistent workaround is to use the non-blocking random generator instead of the blocking one: - -```bash -sudo mount /dev/urandom /dev/random -o bind -``` - -## Quorum Developer Quickstart not working on Apple M1 chip - -The [Quorum Developer Quickstart](../../../private-networks/tutorials/quickstart.md) does not currently support -the Apple M1 chip. The quickstart starts up on machines that use the chip, but may show the -following symptoms: - -* All JSON-RPC calls return an empty reply from the server -* The Grafana dashboard shows no data -* The `docker ps` command displays an AMD message about the containers: - - ```bash - Image may have poor performance, or fail, if run via emulation - ``` - -* No logs can be downloaded - -## Unsupported address exception while running from Docker - -While [running Besu from a Docker image], you might get the following exception: - -```bash -Unsupported address type exception when connecting to peer {}, this is likely due to ipv6 not being enabled at runtime. -``` - -This happens when the IPv6 support in Docker is disabled while connecting to an IPv6 peer, preventing outbound communication. -IPv6 is disabled by default in Docker. - -[Enable IPv6 support in Docker](https://docs.docker.com/config/daemon/ipv6/) to allow outbound IPv6 traffic and allow connection with IPv6 peers. diff --git a/docs/private-networks/get-started/install/run-docker-image.md b/docs/private-networks/get-started/install/run-docker-image.md index fc243fdf..a5b10daf 100644 --- a/docs/private-networks/get-started/install/run-docker-image.md +++ b/docs/private-networks/get-started/install/run-docker-image.md @@ -14,9 +14,9 @@ Use this Docker image to run a single Besu node without installing Besu. * MacOS or Linux -!!! important + !!! important - The Docker image does not run on Windows. + The Docker image doesn't run on Windows. ## Expose ports @@ -70,7 +70,7 @@ docker run -p :8545 -p :8546 -p :3 [`--nat-method`](../../../public-networks/how-to/connect/specify-nat.md) to `NONE` or `UPNP`. You can specify -[Besu environment variables](../../../public-networks/reference/cli/options.md#besu-environment-variables) with the +[Besu environment variables](../../../public-networks/reference/cli/options.md#specify-options) with the Docker image instead of the command line options. !!! example @@ -79,6 +79,21 @@ Docker image instead of the command line options. docker run -p 30303:30303 -p 8545:8545 -e BESU_RPC_HTTP_ENABLED=true -e BESU_NETWORK=goerli hyperledger/besu:latest ``` +??? caution "Unsupported address type exception" + + When running Besu from a Docker image, you might get the following exception: + + ```bash + Unsupported address type exception when connecting to peer {}, this is likely due to ipv6 not being enabled at runtime. + ``` + + This happens when the IPv6 support in Docker is disabled while connecting to an IPv6 peer, + preventing outbound communication. + IPv6 is disabled by default in Docker. + + [Enable IPv6 support in Docker](https://docs.docker.com/config/daemon/ipv6/) to allow outbound + IPv6 traffic and allow connection with IPv6 peers. + ### Run a node for testing To run a node that mines blocks at a rate suitable for testing purposes with WebSocket enabled: diff --git a/docs/private-networks/how-to/configure/consensus/ibft.md b/docs/private-networks/how-to/configure/consensus/ibft.md index f383f0f9..34438b74 100644 --- a/docs/private-networks/how-to/configure/consensus/ibft.md +++ b/docs/private-networks/how-to/configure/consensus/ibft.md @@ -71,15 +71,36 @@ The properties specific to IBFT 2.0 are: !!! caution - We do not recommend changing `epochlength` in a running network. Changing the `epochlength` + We don't recommend changing `epochlength` in a running network. Changing the `epochlength` after genesis can result in illegal blocks. +??? caution "Invalid block header error" + + When adding a new node, if a `TimeStampMoreRecentThanParent | Invalid block header` error occurs, + the genesis file of the new node specifies a higher `blockperiodseconds` than the imported chain. + The imported chain makes new blocks faster than the genesis file allows and Besu rejects them + with this error. + This error most often occurs when importing chains from older versions of Besu. + + Decrease the `blockperiodseconds` in the new IBFT 2.0 genesis file to a lower value that + satisfies the block header validation. + + !!! example + + If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp + 1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`, + decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain. + + After you update the new genesis file, if the imported chain has a `blockperiodseconds` value + set lower than you prefer, you can adjust it by [configuring the block time on an existing IBFT + 2.0 network](#configure-block-time-on-an-existing-network). + The properties with specific values in the IBFT 2.0 genesis files are: * `nonce` - `0x0` * `difficulty` - `0x1` * `mixHash` - `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` for Istanbul - block identification. + block identification To start a node on an IBFT 2.0 private network, use the [`--genesis-file`](../../../../public-networks/reference/cli/options.md#genesis-file) option to specify the custom diff --git a/docs/private-networks/how-to/configure/consensus/qbft.md b/docs/private-networks/how-to/configure/consensus/qbft.md index 073fbbc0..f9a94df0 100644 --- a/docs/private-networks/how-to/configure/consensus/qbft.md +++ b/docs/private-networks/how-to/configure/consensus/qbft.md @@ -155,14 +155,35 @@ The QBFT properties are: !!! caution - We do not recommend changing `epochlength` in a running network. Changing the `epochlength` + We don't recommend changing `epochlength` in a running network. Changing the `epochlength` after genesis can result in illegal blocks. +??? caution "Invalid block header error" + + When adding a new node, if a `TimeStampMoreRecentThanParent | Invalid block header` error occurs, + the genesis file of the new node specifies a higher `blockperiodseconds` than the imported chain. + The imported chain makes new blocks faster than the genesis file allows and Besu rejects them + with this error. + This error most often occurs when importing chains from older versions of Besu. + + Decrease the `blockperiodseconds` in the new QBFT genesis file to a lower value that satisfies + the block header validation. + + !!! example + + If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp + 1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`, + decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain. + + After you update the new genesis file, if the imported chain has a `blockperiodseconds` value + set lower than you prefer, you can adjust it by [configuring the block time on an existing QBFT + network](#configure-block-time-on-an-existing-network). + The properties with specific values in the QBFT genesis files are: * `difficulty` - `0x1` * `mixHash` - `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` for Istanbul - block identification. + block identification To start a node on a QBFT private network, use the [`--genesis-file`](../../../../public-networks/reference/cli/options.md#genesis-file) option to specify the custom diff --git a/docs/private-networks/reference/cli/options.md b/docs/private-networks/reference/cli/options.md index 1727da8d..63a479bc 100644 --- a/docs/private-networks/reference/cli/options.md +++ b/docs/private-networks/reference/cli/options.md @@ -42,6 +42,12 @@ If using Bash or Z shell, you can view option suggestions by entering `--` and p besu --Tab+Tab ``` +!!! caution + + Characters such as smart quotes and long (em) hyphens don't work in Besu command line options. + Ensure quotes aren't automatically converted to smart quotes, or double hyphens combined into em + hyphens. + ## Options ### `permissions-accounts-config-file` diff --git a/docs/public-networks/get-started/install/run-docker-image.md b/docs/public-networks/get-started/install/run-docker-image.md index e5323484..e154adbe 100644 --- a/docs/public-networks/get-started/install/run-docker-image.md +++ b/docs/public-networks/get-started/install/run-docker-image.md @@ -14,9 +14,9 @@ Use this Docker image to run a single Besu node without installing Besu. * MacOS or Linux -!!! important + !!! important - The Docker image does not run on Windows. + The Docker image doesn't run on Windows. ## Default node for Mainnet @@ -86,7 +86,7 @@ docker run -p :8545 -p :8546 -p :3 [`--nat-method`](../../how-to/connect/specify-nat.md) to `NONE` or `UPNP`. You can specify -[Besu environment variables](../../reference/cli/options.md#besu-environment-variables) with the +[Besu environment variables](../../reference/cli/options.md#specify-options) with the Docker image instead of the command line options. !!! example @@ -95,6 +95,21 @@ Docker image instead of the command line options. docker run -p 30303:30303 -p 8545:8545 -e BESU_RPC_HTTP_ENABLED=true -e BESU_NETWORK=goerli hyperledger/besu:latest ``` +??? caution "Unsupported address type exception" + + When running Besu from a Docker image, you might get the following exception: + + ```bash + Unsupported address type exception when connecting to peer {}, this is likely due to ipv6 not being enabled at runtime. + ``` + + This happens when the IPv6 support in Docker is disabled while connecting to an IPv6 peer, + preventing outbound communication. + IPv6 is disabled by default in Docker. + + [Enable IPv6 support in Docker](https://docs.docker.com/config/daemon/ipv6/) to allow outbound + IPv6 traffic and allow connection with IPv6 peers. + ### Run a node for testing To run a node that mines blocks at a rate suitable for testing purposes with WebSocket enabled: diff --git a/docs/public-networks/how-to/connect/manage-peers.md b/docs/public-networks/how-to/connect/manage-peers.md index 02366901..e5e1915c 100644 --- a/docs/public-networks/how-to/connect/manage-peers.md +++ b/docs/public-networks/how-to/connect/manage-peers.md @@ -100,3 +100,15 @@ To disable P2P discovery, set the With discovery disabled, peers can't open connections with the node unless they were previously discovered or manually peered (for example, using [`admin_addPeer`](../../reference/api/index.md#admin_addpeer)). [Static nodes](static-nodes.md) can also open connections. + +## Troubleshoot + +If your nodes fail to connect, ensure the +[required ports are open](configure-ports.md). + +If your nodes are running in AWS, check you have appropriate `SecurityGroups` to allow access to +the required ports. + +Check that the [enode URLs](../../concepts/node-keys.md#enode-url) specified for +[bootnodes](../../../private-networks/how-to/configure/bootnodes.md) or +[static nodes](static-nodes.md) match the enode URLs displayed when starting the remote nodes. diff --git a/docs/public-networks/how-to/connect/sync-node.md b/docs/public-networks/how-to/connect/sync-node.md index 527e7087..fc060359 100644 --- a/docs/public-networks/how-to/connect/sync-node.md +++ b/docs/public-networks/how-to/connect/sync-node.md @@ -56,7 +56,17 @@ Using fast sync with [private transactions](../../../private-networks/concepts/p You can observe the `besu_synchronizer_fast_sync_*` and `besu_synchronizer_world_state_*` [metrics](../monitor/metrics.md#metrics-list) to monitor fast sync. -!!! warning +!!! note + + When fast syncing, block numbers increase until close to the head block, then the process pauses + while the world state download completes. + This may take a significant amount of time depending on world state size, during which the + current head block doesn't increase. + For example, Mainnet may take several days or more to fast sync. + Fast sync time may increase because Besu picks new pivot blocks, or because peers prune the + world state before it completes downloading. + +!!! caution "RocksDB error on AWS" When running Besu on some cloud providers, a known [RocksDB](https://github.com/facebook/rocksdb/issues/6435) issue causes fast sync to fail occasionally. @@ -71,15 +81,21 @@ You can observe the `besu_synchronizer_fast_sync_*` and `besu_synchronizer_world On AWS, A full restart of the VM is required to restart the fast sync. Fast sync isn't [currently supported on Digital Ocean](https://github.com/hyperledger/besu/blob/750580dcca349d22d024cc14a8171b2fa74b505a/CHANGELOG.md#143). -!!! note +!!! caution "Pending state nodes stays constant" - When fast syncing, block numbers increase until close to the head block, then the process pauses while the world - state download completes. - This may take a significant amount of time depending on world state size, during which the current head block - doesn't increase. - For example, Mainnet may take several days or more to fast sync. - Fast sync time may increase because Besu picks new pivot blocks, or because peers prune the world state before it - completes downloading. + When fast syncing, the pending state nodes count is the number of nodes yet to be downloaded, and + it should change constantly. + Pending state nodes trend to 0 during fast sync and then goes to 0. + + If the number stays constant, this could mean your node isn't syncing against any peers. + + In the following example, the pivot block is 0 and the pending state nodes value is constant. + This means the node isn't syncing against any peers. + The fact that state nodes have been downloaded means at some stage it was syncing. + + ![Fast synchronization](../../../assets/images/fastsync.png) + + The easiest solution in this scenario is to restart fast sync to obtain a new pivot block. ### Snap synchronization diff --git a/docs/public-networks/how-to/use-besu-api/index.md b/docs/public-networks/how-to/use-besu-api/index.md index b3803353..fba2a380 100644 --- a/docs/public-networks/how-to/use-besu-api/index.md +++ b/docs/public-networks/how-to/use-besu-api/index.md @@ -88,11 +88,11 @@ If your application publishes RPC ports, specify the hostnames when starting Bes besu --host-allowlist=example.com ``` -Specify "*" for `--host-allowlist` to effectively disable host protection. +Specify `*` for `--host-allowlist` to effectively disable host protection. !!! caution - Specifying "*" for `--host-allowlist` is not recommended for production code. + Specifying `*` for `--host-allowlist` is not recommended for production code. ## Not supported by Besu diff --git a/docs/public-networks/how-to/use-pow/mining.md b/docs/public-networks/how-to/use-pow/mining.md index e6060010..8f2cfa4f 100644 --- a/docs/public-networks/how-to/use-pow/mining.md +++ b/docs/public-networks/how-to/use-pow/mining.md @@ -86,12 +86,52 @@ get the miner data for a specified block. * [`eth_submitWork`](../../reference/api/index.md#eth_submitwork) to submit the PoW solution. Only used when using the `getwork` scheme. -## Hyperledger Besu mined blocks +## Besu mined blocks -Hyperledger Besu has successfully mined blocks on the Ropsten testnet, ETC Mainnet (uncle block only) and Mordor ETC testnet. +Besu has successfully mined blocks on the Ropsten testnet, ETC Mainnet (uncle block only) and Mordor ETC testnet. Blocks mined by the Hyperledger Besu team contain the version number used in the block's `extraData` field. The following accounts have been used to mine on public networks with Hyperledger Besu: * **Ropsten**: [`0x2f14582947E292a2eCd20C430B46f2d27CFE213c`](https://ropsten.etherscan.io/address/0x2f14582947E292a2eCd20C430B46f2d27CFE213c#mine) * **ETC**: [`0x3125309aa670f5e60493b50884a7e7abf9ebb701`](https://etc.tokenview.com/en/address/0x3125309aa670f5e60493b50884a7e7abf9ebb701) * **Mordor**: `0x2f14582947E292a2eCd20C430B46f2d27CFE213c` + +## Troubleshoot + +### Check block creation + +On mining nodes, log messages indicate block creation. + +!!! example + + ```bash + 2019-05-08 20:28:27.026+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=660, Round=0}, hash=0x759afaba4e923d89175d850ceca4b8ef81f7d9c727b0b0b8e714b624a4b8e8cc + 2019-05-08 20:28:29.020+10:00 | pool-10-thread-1 | INFO | IbftRound | Importing block to chain. round=ConsensusRoundIdentifier{Sequence=661, Round=0}, hash=0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14 + ``` + +On non-mining nodes, log messages indicate importing blocks. + +!!! example + + ```bash + 2019-05-08 20:28:29.026+10:00 | EthScheduler-Workers-1 | INFO | BlockPropagationManager | Imported #661 / 0 tx / 0 om / 0 (0.0%) gas / (0x5443e504256765f06b3cebfbee82276a034ebcc8d685b7c3d1a6010fd4acfa14) in 0.000s. + 2019-05-08 20:28:31.031+10:00 | EthScheduler-Workers-0 | INFO | BlockPropagationManager | Imported #662 / 0 tx / 0 om / 0 (0.0%) gas / (0x0ead4e20123d3f1433d8dec894fcce386da4049819b24b309963ce7a8a0fcf03) in 0.000s. + ``` + +To confirm the block number is increasing, use the +[`eth_blockNumber`](../../reference/api/index.md#eth_blocknumber) JSON-RPC API method. + +If there's no block creation in [Clique](../../../private-networks/how-to/configure/consensus/clique.md#extra-data) +or [IBFT 2.0](../../../private-networks/how-to/configure/consensus/ibft.md#extra-data) networks, +ensure the validator addresses in the genesis file match running nodes. + +### No mined transactions + +If you add a transaction to the [transaction pool](../../concepts/transactions/pool.md) and the +transaction hash returns, but the transaction is never mined, check the +[`--min-gas-price`](../../reference/cli/options.md#min-gas-price) option on mining nodes. +If the `gasPrice` on a [transaction](../send-transactions.md) is lower than the `min-gas-price` for +the mining node, the transaction will never mine. + +In [free gas networks](../../../private-networks/how-to/configure/free-gas.md), you must set +[`--min-gas-price`](../../reference/cli/options.md#min-gas-price) to zero. diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md index d7a4d962..143473ce 100644 --- a/docs/public-networks/reference/cli/options.md +++ b/docs/public-networks/reference/cli/options.md @@ -43,6 +43,12 @@ If using Bash or Z shell, you can view option suggestions by entering `--` and p besu --Tab+Tab ``` +!!! caution + + Characters such as smart quotes and long (em) hyphens don't work in Besu command line options. + Ensure quotes aren't automatically converted to smart quotes, or double hyphens combined into em + hyphens. + ## Options ### `api-gas-price-blocks` diff --git a/docs/public-networks/reference/genesis-items.md b/docs/public-networks/reference/genesis-items.md index 58ab9ea7..3f236a96 100644 --- a/docs/public-networks/reference/genesis-items.md +++ b/docs/public-networks/reference/genesis-items.md @@ -50,6 +50,13 @@ consensus protocols. | `timestamp` | Creation date and time of the block. Must be before the next block so we recommend specifying `0x0` in the genesis file. | | `alloc` | Defines [accounts with balances](../../private-networks/reference/accounts-for-testing.md) or [contracts](../../private-networks/how-to/configure/contracts.md). | +!!! caution + + If a `Supplied genesis block does not match stored chain data` error occurs, use the genesis + file matching the genesis block of the data directory, or use the + [`--data-path`](../reference/cli/options.md#data-path) option to specify a different data + directory. + ## Milestone blocks In public networks, the milestone blocks specify the blocks at which the network changed protocol. @@ -82,6 +89,11 @@ and their corresponding milestone blocks. } ``` +!!! caution + + Ensure you include a milestone far enough in advance in the genesis file. + Not doing so can lead to unexpected and inconsistent behavior without specific errors. + In private networks, the milestone block defines the protocol version for the network. !!! example "Private network milestone block" @@ -98,9 +110,9 @@ In private networks, the milestone block defines the protocol version for the ne !!! note - We recommend specifying the latest milestone block for private networks. - It is implied this includes the preceding milestones. - This ensures you are using the most up-to-date protocol and have access to the most recent opcodes. + In private networks, we recommend specifying the latest milestone block. + It's implied this includes the preceding milestones. + This ensures you use the most up-to-date protocol and have access to the most recent opcodes. ## Fixed difficulty diff --git a/mkdocs.navigation.yml b/mkdocs.navigation.yml index e2ce655d..1a6bcc5d 100644 --- a/mkdocs.navigation.yml +++ b/mkdocs.navigation.yml @@ -104,7 +104,7 @@ nav: - Consensus: - private-networks/how-to/configure/consensus/index.md - QBFT: private-networks/how-to/configure/consensus/qbft.md - - IBFT: private-networks/how-to/configure/consensus/ibft.md + - IBFT 2.0: private-networks/how-to/configure/consensus/ibft.md - Clique: private-networks/how-to/configure/consensus/clique.md - Add and remove validators without voting: private-networks/how-to/configure/consensus/add-validators-without-voting.md - Free gas network: private-networks/how-to/configure/free-gas.md